From a0e49dce66ff68dbcb8fa84a935b5abde1250fe7 Mon Sep 17 00:00:00 2001 From: Nikki Massaro Date: Mon, 16 Sep 2024 14:56:42 -0400 Subject: [PATCH 01/33] docs: accessibility docs --- packages/action-bar/README.md | 2 +- packages/action-button/README.md | 166 ++++-- packages/action-menu/README.md | 8 +- packages/button-group/README.md | 14 +- packages/button/README.md | 170 ++++-- packages/help-text/README.md | 113 +++- packages/menu/README.md | 215 ++++++- packages/menu/menu-group.md | 176 +++++- packages/menu/menu-item.md | 255 +++++++-- packages/picker/README.md | 531 ++++++++++++------ projects/documentation/.eleventy.js | 106 +++- .../documentation/content/_includes/api.njk | 3 +- .../content/_includes/changelog.njk | 3 +- .../content/_includes/component.njk | 18 +- .../content/_includes/examples.njk | 5 +- .../content/_includes/partials/demo.njk | 12 +- .../content/guides/adding-component.md | 56 ++ .../documentation/src/components/styles.css | 42 +- 18 files changed, 1480 insertions(+), 415 deletions(-) diff --git a/packages/action-bar/README.md b/packages/action-bar/README.md index a5beb6535e..5666c09817 100644 --- a/packages/action-bar/README.md +++ b/packages/action-bar/README.md @@ -1,4 +1,4 @@ -## Description +## Overview A `` delivers a floating action bar that is a convenient way to deliver stateful actions in cases like selection mode. `` can be deployed in two variants beyond the default: `[varient="fixed"]` to position the element in relation to the page, and `[variant=sticky]` to position the content in relation to content that may scroll. diff --git a/packages/action-button/README.md b/packages/action-button/README.md index 2e28fcc8bb..3d37c7476c 100644 --- a/packages/action-button/README.md +++ b/packages/action-button/README.md @@ -1,4 +1,4 @@ -## Description +## Overview An `` represents an action a user can take. @@ -24,9 +24,11 @@ When looking to leverage the `ActionButton` base class as a type and/or for exte import { ActionButton } from '@spectrum-web-components/action-button'; ``` -## Sizes +### Options - +#### Sizes + + Extra Small @@ -129,11 +131,13 @@ import { ActionButton } from '@spectrum-web-components/action-button'; -## Variants +#### Variants The `` can be customized with either or both of the `emphasized` and `quiet` attributes. These will pair with either or both of the state attributes (`selected` and `disabled`) to decide the final visual delivery of the ``. Content addressed to the `icon` slot can also be provided and will be positioned just before the rest of the the supplied button content. -### Standard + +Default + ```html demo
` can be customized with either or both of the `emphasize
``` -### Quiet + +Quiet + ```html demo
` can be customized with either or both of the `emphasize
``` -### Emphasized + +Emphasized + ```html demo
` can be customized with either or both of the `emphasize
``` -### Emphasized + Quiet + +Emphasized + quiet + ```html demo
` can be customized with either or both of the `emphasize
``` -## Action button with hold affordance + + + +### Behaviors + +#### Action button with hold affordance The use of the `hold-affordance` attribute signifies that the `` in question will be delivered with a visual affordance outlining that special interaction with the button will dispatch a `longpress` event. Via a pointer input, this even will be dispatched when 300ms has passed after a `pointerdown` event without the presence of a `pointerup` or `pointercancel` event. Via the keyboard, an event with a code of `Space` or or `ArrowDown` while `altKey === true` will dispatch the event. @@ -499,44 +514,109 @@ The use of the `hold-affordance` attribute signifies that the ` ``` -## Toggles +#### Toggles With the application of the `toggles` attribute, the button will self manage its `selected` property on `click`. When this value is updated, a cancellable `change` event will be dispatched to inform the parent application. + +Default + + ```html demo -
Toggle button + + Toggle button + +``` + + +Quiet + + +```html demo + + Toggle button + + + Toggle button + +``` + + +Emphasized + + +```html demo + + Toggle button + + + Toggle button + +``` + + +Emphasized + Quiet + + +```html demo + + Toggle button + + -
- Standard - - Toggle button - -
-
- Quiet - - Toggle button - -
-
- Emphasized - - Toggle button - -
-
- - Emphasized + Quiet - - - Toggle button - -
+ Toggle button + +``` + + + + +### Accessibility guidelines + +#### Include a label + +A button is required to have either a visible text label or `label` attribute on an `` +or on an `` element child. + +#### Don't override color + +Do not use custom colors for buttons. The colors of different button variations have been designed to be consistent and accessible. + +#### Use static black or static white to contrast with backgrounds and images + +To ensure maximum contrast with the background, use static black for light backgrounds and images, and use static white for dark backgrounds and images. Avoid placing static components on top of busy images with a lot of variance in contrast. + + +Static black on light background + + +```html demo +
+ Click me + Click me
``` + + +Static white on dark background + + +```html demo +
+ Click me + Click me +
+``` + + + + +#### Clearly state the action + +Make sure that an action button’s label clearly states the outcome of the action. Use the same word or phrase as found elsewhere in the experience. diff --git a/packages/action-menu/README.md b/packages/action-menu/README.md index e3dcf729a6..2790a9d1e6 100644 --- a/packages/action-menu/README.md +++ b/packages/action-menu/README.md @@ -1,4 +1,4 @@ -## Description +## Overview An `` is an action button that triggers an overlay with `` for activation. Use an `` element to outline the items that will be made available to the user when interacting with the `` element. By default `` does not manage a selection. If you'd like for a selection to be held by the `` that is presented in its overlay, use `selects="single"` to activate this functionality. @@ -30,9 +30,11 @@ When looking to leverage the `ActionMenu` base class as a type and/or for extens import { ActionMenu } from '@spectrum-web-components/action-menu'; ``` -## Sizes +### Options - +#### Sizes + + Small diff --git a/packages/button-group/README.md b/packages/button-group/README.md index 27dc7dfc73..8d8553def0 100644 --- a/packages/button-group/README.md +++ b/packages/button-group/README.md @@ -1,4 +1,4 @@ -## Description +## Overview `sp-button-group` delivers a set of buttons in horizontal or vertical orientation while ensuring the appropriate spacing between those buttons. @@ -24,7 +24,11 @@ When looking to leverage the `ButtonGroup` base class as a type and/or for exten import { ButtonGroup } from '@spectrum-web-components/button-group'; ``` -## Horizontal +### Options + +A button group can be either horizontal or vertical in its orientation. By default, a button group is horizontal. Use vertical option when horizontal space is limited. + +#### Horizontal ```html @@ -34,7 +38,7 @@ import { ButtonGroup } from '@spectrum-web-components/button-group'; ``` -## Vertical +#### Vertical ```html @@ -43,3 +47,7 @@ import { ButtonGroup } from '@spectrum-web-components/button-group'; Short 3 ``` + +### Accessibility guidelines + +Review the guidelines for the [button](../button#accessibility-guidelines) children. diff --git a/packages/button/README.md b/packages/button/README.md index 7f138d4f96..90928e9e6a 100644 --- a/packages/button/README.md +++ b/packages/button/README.md @@ -1,4 +1,4 @@ -## Description +## Overview An `` represents an action a user can take. sp-buttons can be clicked or tapped to perform an action or to navigate to another page. sp-buttons in @@ -29,9 +29,78 @@ When looking to leverage the `Button`, `ClearButton`, or `CloseButton` base clas import { Button, ClearButton, CloseButton } from '@spectrum-web-components/button'; ``` -## Sizes +### Anatomy - +#### Content + +`` elements can be provided a visible label, +a label with an icon, or just an icon. + +An icon is provided by placing an icon element to the `icon` slot. + +If the button is an icon only, a non-visible label +can be provided via the `label` attribute on an `` +or on an `` element child to appropriately +fulfill the accessibility contract of the button. + + +Label only + + +```html demo +Label only +``` + + +Icon + label + + +```html demo + + + Icon + Label + +``` + + +SVG Icon + label + + +```html demo + + + SVG Icon + Label + +``` + + +Icon only + + +```html demo + + + +``` + + + + +### Options + +#### Sizes + + Small @@ -66,39 +135,7 @@ import { Button, ClearButton, CloseButton } from '@spectrum-web-components/butto -## Content - -`` elements can be provided a visible label, a label with an icon, or just an icon (a non-visible label can be prived via the `label` attribute on an `` or on an `` element child to appropriately fulfill the accessibility contract of the button). An icon is provided by -placing an icon element to the `icon` slot. - -```html - - Label only - - - Icon + Label - - - - SVG Icon + Label - - - - - -``` - -## Variants +#### Variants There are many button variants to choose from in Spectrum. The `variant` attribute defaults to `accent` but also accepts the following value: `accent`, `primary`, `secondary`, `negative`, `white`, and `black`. They display as follows: @@ -208,7 +245,7 @@ attribute defaults to `accent` but also accepts the following value: `accent`, ` -### Treatment +#### Treatment The `treatment` attribute accepts `fill` and `outline` as values, and defaults to `fill`. These display as follows: @@ -283,7 +320,7 @@ The `treatment` attribute accepts `fill` and `outline` as values, and defaults t -## States +### States In addition to the variant, `` elements support two different visual states, disabled and pending, which can be applied by adding the attribute `disabled` or `pending` respectively. All `` variants support these states. @@ -300,11 +337,10 @@ While disabled, `` elements will not respond to click events and will ### Pending -While in pending state, `` elements will not respond to click events and will appear faded with an indeterminent ``. +While in pending state, `` elements will not respond to click events and will appear faded with an indeterminate ``. `` elements label and icon will be hidden while in pending state. -Note: `pending` state of the `` element is applied after 1s delay to avoid flashing the pending state for quick actions. -You can override the delay by adding custom css var `--pending-delay` to your css. +Note: `pending` state of the `` element is applied after 1s delay to avoid flashing the pending state for quick actions. You can override the delay by adding custom css var `--pending-delay` to your css. ```html @@ -313,7 +349,9 @@ You can override the delay by adding custom css var `--pending-delay` to your cs ``` -## Handling events +### Behaviors + +#### Handling events Events handlers for clicks and other user actions can be registered on a `` as on a standard HTML `