diff --git a/.stylelintrc.json b/.stylelintrc.json index 53ed72c15c..00288d1ad0 100755 --- a/.stylelintrc.json +++ b/.stylelintrc.json @@ -6,7 +6,9 @@ "length-zero-no-unit": [true, { "ignore": "custom-properties" }], "selector-type-no-unknown": [true, { "ignore": ["custom-elements"] }], "selector-pseudo-element-colon-notation": ["single", {}], - "custom-property-pattern": "^_?([a-z][a-z0-9]*)(-[a-z0-9]+)*$" + "custom-property-pattern": "^_?([a-z][a-z0-9]*)(-[a-z0-9]+)*$", + "no-duplicate-selectors": null, + "no-descending-specificity": null }, "overrides": [ { 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..c2a7ddc334 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 a `label` attribute on either the `` itself, +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 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..b61e258464 100644 --- a/packages/action-menu/README.md +++ b/packages/action-menu/README.md @@ -1,6 +1,6 @@ -## 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. +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 managed, use `selects="single"` on the `` to activate this functionality. ### Usage @@ -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 b06bb99717..59cc178c3b 100644 --- a/packages/button/README.md +++ b/packages/button/README.md @@ -1,7 +1,7 @@ -## 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 +or tapped to perform an action or to navigate to another page. Buttons in Spectrum have several variations for different uses and multiple levels of loudness for various attention-getting needs. @@ -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 and an icon, or just an icon. + +An icon is provided by placing an icon element in the `icon` slot. + +If the button is `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,42 +135,10 @@ 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: +attribute defaults to `accent`, but also accepts the following value: `accent`, `primary`, `secondary`, `negative`, `white`, and `black`. They display as follows: Accent @@ -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: @@ -293,11 +330,11 @@ 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. -### Disabled +#### Disabled While disabled, `` elements will not respond to click events and will appear faded. @@ -308,13 +345,12 @@ While disabled, `` elements will not respond to click events and will ``` -### Pending +#### Pending -While in pending state, `` elements will not respond to click events and will appear faded with an indeterminent ``. -`` elements label and icon will be hidden while in pending state. +While in pending state, `` elements will not respond to click events and will appear faded with an indeterminate ``. +The `` element's 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: The pending state of the `` element is applied after a 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 @@ -323,10 +359,12 @@ 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 `