[DO NOT MERGE]: accessibility docs for SWC07

.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": [
         {

packages/action-bar/README.md

@@ -1,4 +1,4 @@
-## Description
+## Overview
 
 A `<sp-action-bar>` delivers a floating action bar that is a convenient way to deliver stateful actions in cases like selection mode. `<sp-action-bar>` 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.
 

packages/action-button/README.md

@@ -1,4 +1,4 @@
-## Description
+## Overview
 
 An `<sp-action-button>` 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
 
-<sp-tabs selected="m" auto label="Size Attribute Options">
+#### Sizes
+
+<sp-tabs selected="m" auto label="Size attribute options">
 <sp-tab value="xs">Extra Small</sp-tab>
 <sp-tab-panel value="xs">
 
@@ -129,11 +131,13 @@ import { ActionButton } from '@spectrum-web-components/action-button';
 </sp-tab-panel>
 </sp-tabs>
 
-## Variants
+#### Variants
 
 The `<sp-action-button>` 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 `<sp-action-button>`. 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
+<sp-tabs selected="default" auto label="Variant options">
+<sp-tab value="default">Default</sp-tab>
+<sp-tab-panel value="default">
 
 ```html demo
 <div
@@ -211,7 +215,9 @@ The `<sp-action-button>` can be customized with either or both of the `emphasize
 </div>
 ```
 
-### Quiet
+</sp-tab-panel>
+<sp-tab value="quiet">Quiet</sp-tab>
+<sp-tab-panel value="quiet">
 
 ```html demo
 <div
@@ -289,7 +295,9 @@ The `<sp-action-button>` can be customized with either or both of the `emphasize
 </div>
 ```
 
-### Emphasized
+</sp-tab-panel>
+<sp-tab value="emphasized">Emphasized</sp-tab>
+<sp-tab-panel value="emphasized">
 
 ```html demo
 <div
@@ -369,7 +377,9 @@ The `<sp-action-button>` can be customized with either or both of the `emphasize
 </div>
 ```
 
-### Emphasized + Quiet
+</sp-tab-panel>
+<sp-tab value="emq">Emphasized + quiet</sp-tab>
+<sp-tab-panel value="emq">
 
 ```html demo
 <div
@@ -455,7 +465,12 @@ The `<sp-action-button>` can be customized with either or both of the `emphasize
 </div>
 ```
 
-## Action button with hold affordance
+</sp-tab-panel>
+</sp-tabs>
+
+### Behaviors
+
+#### Action button with hold affordance
 
 The use of the `hold-affordance` attribute signifies that the `<sp-action-button>` 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 `<sp-action-button
 </div>
 ```
 
-## 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.
 
+<sp-tabs selected="default" auto label="Toggled action buttons">
+<sp-tab value="default">Default</sp-tab>
+<sp-tab-panel value="default">
+
 ```html demo
-<div
-    style="display: grid; grid-template-columns: repeat(auto-fill, minmax(100px, 1fr)); gap: 2em;"
+<sp-action-button toggles id="toggles-default">Toggle button</sp-action-button>
+<sp-action-button toggles selected id="toggles-default">
+    Toggle button
+</sp-action-button>
+```
+
+</sp-tab-panel>
+<sp-tab value="quiet">Quiet</sp-tab>
+<sp-tab-panel value="quiet">
+
+```html demo
+<sp-action-button toggles quiet id="toggles-quiet">
+    Toggle button
+</sp-action-button>
+<sp-action-button toggles quiet selected id="toggles-quiet">
+    Toggle button
+</sp-action-button>
+```
+
+</sp-tab-panel>
+<sp-tab value="emphasized">Emphasized</sp-tab>
+<sp-tab-panel value="emphasized">
+
+```html demo
+<sp-action-button toggles emphasized id="toggles-emphasized">
+    Toggle button
+</sp-action-button>
+<sp-action-button toggles emphasized selected id="toggles-emphasized">
+    Toggle button
+</sp-action-button>
+```
+
+</sp-tab-panel>
+<sp-tab value="emphasized-quiet">Emphasized + Quiet</sp-tab>
+<sp-tab-panel value="emphasized-quiet">
+
+```html demo
+<sp-action-button toggles emphasized quiet id="toggles-emphasized-quiet">
+    Toggle button
+</sp-action-button>
+<sp-action-button
+    toggles
+    emphasized
+    quiet
+    selected
+    id="toggles-emphasized-quiet"
 >
-    <div>
-        <sp-field-label for="toggles-default">Standard</sp-field-label>
-        <sp-action-button toggles id="toggles-default">
-            Toggle button
-        </sp-action-button>
-    </div>
-    <div>
-        <sp-field-label for="toggles-quiet">Quiet</sp-field-label>
-        <sp-action-button toggles quiet id="toggles-quiet">
-            Toggle button
-        </sp-action-button>
-    </div>
-    <div>
-        <sp-field-label for="toggles-emphasized">Emphasized</sp-field-label>
-        <sp-action-button toggles emphasized id="toggles-emphasized">
-            Toggle button
-        </sp-action-button>
-    </div>
-    <div>
-        <sp-field-label for="toggles-emphasized-quiet">
-            Emphasized + Quiet
-        </sp-field-label>
-        <sp-action-button
-            toggles
-            emphasized
-            quiet
-            id="toggles-emphasized-quiet"
-        >
-            Toggle button
-        </sp-action-button>
-    </div>
+    Toggle button
+</sp-action-button>
+```
+
+</sp-tab-panel>
+</sp-tabs>
+
+### Accessibility guidelines
+
+#### Include a label
+
+A button is required to have either a visible text label or a `label` attribute on either the `<sp-button>` itself,
+or on an `<sp-icon*>` 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.
+
+<sp-tabs selected="black" auto label="Static variants for contrast">
+<sp-tab value="black">Static black on light background</sp-tab>
+<sp-tab-panel value="black">
+
+```html demo
+<div style="background-color: #ccffee; padding: 20px">
+    <sp-action-button static="black">Click me</sp-action-button>
+    <sp-action-button static="black" selected>Click me</sp-action-button>
 </div>
 ```
+
+</sp-tab-panel>
+<sp-tab value="white">Static white on dark background</sp-tab>
+<sp-tab-panel value="white">
+
+```html demo
+<div style="background-color: #220033; padding: 20px">
+    <sp-action-button static="white">Click me</sp-action-button>
+    <sp-action-button static="white" selected>Click me</sp-action-button>
+</div>
+```
+
+</sp-tab-panel>
+</sp-tabs>
+
+#### 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.

packages/action-menu/README.md

@@ -1,6 +1,6 @@
-## Description
+## Overview
 
-An `<sp-action-menu>` is an action button that triggers an overlay with `<sp-menu-items>` for activation. Use an `<sp-menu>` element to outline the items that will be made available to the user when interacting with the `<sp-action-menu>` element. By default `<sp-action-menu>` does not manage a selection. If you'd like for a selection to be held by the `<sp-menu>` that is presented in its overlay, use `selects="single"` to activate this functionality.
+An `<sp-action-menu>` is an action button that triggers an overlay with `<sp-menu-items>` for activation. Use an `<sp-menu>` element to outline the items that will be made available to the user when interacting with the `<sp-action-menu>` element. By default, `<sp-action-menu>` does not manage a selection. If you'd like for a selection to be managed, use `selects="single"` on the `<sp-menu>` 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
 
-<sp-tabs selected="m" auto label="Size Attribute Options">
+#### Sizes
+
+<sp-tabs selected="m" auto label="Size attribute options">
 <sp-tab value="s">Small</sp-tab>
 <sp-tab-panel value="s">
 

packages/asset/README.md

@@ -1,4 +1,4 @@
-## Description
+## Overview
 
 Use an `<sp-asset>` element to visually represent a file, folder or image in your application. File and folder representations will center themselves horizontally and vertically in the space provided to the element. Images will be contained to the element, growing to the element's full height while centering itself within the width provided.
 
@@ -24,28 +24,46 @@ When looking to leverage the `Asset` base class as a type and/or for extension p
 import { Asset } from '@spectrum-web-components/asset';
 ```
 
-## Example
+### Anatomy
+
+An asset has a single default `slot`. Use this slot for an image asset.
 
 ```html
 <sp-asset style="height: 128px">
     <img src="https://picsum.photos/500/500" alt="Demo Image" />
 </sp-asset>
 ```
 
-### File
+### Options
+
+#### Variant
+
+Use `variant="file"`for a representation of a file or `variant="folder"` a representation of a folder.
 
 ```html
 <div class="flex">
     <sp-asset variant="file"></sp-asset>
-    <sp-asset variant="file" label="Named File Asset"></sp-asset>
+    <sp-asset variant="folder"></sp-asset>
 </div>
 ```
 
-### Folder
+### Accessibility
+
+#### Use alt text for slotted images
+
+```html
+<sp-asset style="height: 128px">
+    <img src="https://picsum.photos/500/500" alt="Demo Image" />
+</sp-asset>
+```
+
+#### Use the `label` property to provide a descriptive label for variants
+
+You can use the `label` property to provide a descriptive label. If a `label` is not provided, assets with `variant="file"` will be labelled "File" assets with and `variant="folder"` will be labelled with "Folder".
 
 ```html
 <div class="flex">
-    <sp-asset variant="folder"></sp-asset>
+    <sp-asset variant="file" label="Named File Asset"></sp-asset>
     <sp-asset variant="folder" label="Named Folder Asset"></sp-asset>
 </div>
 ```

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
 <sp-button-group>
@@ -34,7 +38,7 @@ import { ButtonGroup } from '@spectrum-web-components/button-group';
 </sp-button-group>
 ```
 
-## Vertical
+#### Vertical
 
 ```html
 <sp-button-group vertical>
@@ -43,3 +47,7 @@ import { ButtonGroup } from '@spectrum-web-components/button-group';
     <sp-button>Short 3</sp-button>
 </sp-button-group>
 ```
+
+### Accessibility guidelines
+
+Review the guidelines for the [button](../button#accessibility-guidelines) children.