docs: updated accessibility section

packages/accordion/accessibility.md

@@ -0,0 +1,14 @@
+### Keyboard interactions
+
+Each accordion is a tab stop. Space or Enter keys expand or collapse accordions, which are collapsed by default. Interactive elements within expanded accordions integrate into the tab order automatically.
+
+### Development considerations
+
+Keep these considerations in mind if you are modifying Spectrum Web Components or creating a custom component:
+
+-   The accordion header has a role of `<sp-button>`, with an aria-expanded attribute set to "true" or "false".
+-   The button has an aria-controls property set to the unique id of the panel it controls.
+-   Since accordions are typically grouped together, Spectrum Web Components puts each button inside a list item in an unordered list, which provides additional context to screen reader users; where only one accordion is used, it should not be put in a list.
+-   When accordion titles are used as headings, the buttons are also wrapped in an element with an appropriate heading level; ARIA can be used to set both the heading role and the level (via aria-level).
+
+See the [ARIA authoring practices](https://www.w3.org/TR/wai-aria-practices-1.2/#accordion) for more guidance.

projects/documentation/content/_includes/accessibility.njk

@@ -0,0 +1,12 @@
+---
+layout: component-partial.njk
+---
+<sp-tabs
+    selected="accessibility"
+    direction="horizontal"
+    aria-labelledby="component-name"
+>
+    <sp-tab value="examples">Examples</sp-tab>
+    <sp-tab value="api">API</sp-tab>
+    <sp-tab value="accessibility">Accessibility</sp-tab>
+

projects/documentation/content/_includes/api.njk

@@ -7,4 +7,5 @@ layout: component-partial.njk
     aria-labelledby="component-name"
 >
     <sp-tab value="examples">Examples</sp-tab>
-    <sp-tab value="api">API</sp-tab>
+    <sp-tab value="api">API</sp-tab>
+    <sp-tab value="accessibility">Accessibility</sp-tab>

projects/documentation/content/_includes/component.njk

@@ -15,6 +15,9 @@ layout: layout.njk
       {% for part in collections[componentName] %}
         <sp-tab-panel class="section" value="{{ part.data.partType }}">
             {{ part.templateContent | safe }}
+            {% if isComponentTemplate and part.data.partType === 'accessibility' %}
+              {% include "partials/accessibility.njk" %}
+            {% endif %}
         </sp-tab-panel>
       {% endfor %}
       </sp-tabs>

projects/documentation/content/_includes/examples.njk

@@ -15,4 +15,5 @@ layout: component.njk
     {% endfor %}
     {% if hasAPI === true %}
         <sp-tab value="api">API</sp-tab>
-    {% endif %}
+    {% endif %}
+     <sp-tab value="accessibility">Accessibility</sp-tab>

projects/documentation/content/_includes/partials/accessibility.njk

@@ -0,0 +1,84 @@
+ <div class="headerContainer">
+    <h2 id="accessibility" tabindex="-1" class="spectrum-Heading spectrum-Heading--sizeM">Accessibility testing status&nbsp;<sp-link class="header-anchor" href="#accessibility" aria-label="Accessibility" dir="ltr" focusable="">#</sp-link></h2>      
+    <sp-divider size="l" dir="ltr" role="separator"></sp-divider>
+</div>
+    <sp-table quiet style="--mod-table-row-background-color-hover: none">
+    <sp-table-head>
+        <sp-table-head-cell>Component</sp-table-head-cell>
+        <sp-table-head-cell>Accessibility test</sp-table-head-cell>
+        <sp-table-head-cell>Accessibility Contract</sp-table-head-cell>
+        <sp-table-head-cell>Status</sp-table-head-cell>
+    </sp-table-head>
+    <sp-table-body>
+        <sp-table-row value="row1">
+            <sp-table-cell><sp-link href="https://opensource.adobe.com/spectrum-web-components/components/{{componentName}}/#usage">{{componentName}}</sp-link></sp-table-cell>
+            <sp-table-cell>
+               <sp-button static="white" style="--mod-bold-font-weight:400">Default state</sp-button>
+            </sp-table-cell>
+            <sp-table-cell>
+                <sp-button static="white" style="--mod-bold-font-weight:400">Test(s) that ensure the initial render state of a component is accessible.</sp-button></sp-table-cell>
+            <sp-table-cell>
+                <sp-button id="trigger-1" variant="secondary" style="--mod-button-background-color-default: #a7f0ba;">Tested</sp-button>
+                <sp-overlay trigger="trigger-1@hover" placement="bottom">
+                    <sp-tooltip>
+                        Passes all automated tests with no reported accessibility violations.
+                    </sp-tooltip>
+                </sp-overlay>
+            </sp-table-cell>
+        </sp-table-row>
+        <sp-table-row value="row2">
+            <sp-table-cell></sp-table-cell>
+            <sp-table-cell>
+                <sp-button static="white" style="--mod-bold-font-weight:400">Advanced states</sp-button>
+            </sp-table-cell>
+            <sp-table-cell>
+                    <sp-button static="white" style="--mod-bold-font-weight:400">Tests that ensure additional states of the component are accessible. 
+                    This could be interactive states of a component or its multiple variants.</sp-button>
+            </sp-table-cell>
+            <sp-table-cell>
+            <sp-button   id="trigger-2" variant="secondary" style="--mod-button-background-color-default: #a7f0ba;">Tested</sp-button>
+            <sp-overlay trigger="trigger-2@hover" placement="bottom">
+                <sp-tooltip>
+                    Passes all automated tests with no reported accessibility violations.
+                </sp-tooltip>
+            </sp-overlay>
+            </sp-table-cell>
+        </sp-table-row>
+         <sp-table-row value="row2">
+            <sp-table-cell></sp-table-cell>
+            <sp-table-cell>
+                <sp-button static="white" style="--mod-bold-font-weight:400">Keyboard navigation</sp-button>
+            </sp-table-cell>
+            <sp-table-cell>
+                    <sp-button static="white" style="--mod-bold-font-weight:400">Tests that ensure focus is properly managed, and all interactive functions of a 
+                        component have a proper keyboard-accessible equivalent.</sp-button>
+            </sp-table-cell>
+            <sp-table-cell>
+             <sp-button id="trigger-3" variant="secondary" style="--mod-button-background-color-default: #a7f0ba;">Tested</sp-button>
+            <sp-overlay trigger="trigger-3@hover" placement="bottom">
+                <sp-tooltip>
+                    Passes all automated tests with no reported accessibility violations.
+                </sp-tooltip>
+            </sp-overlay>
+            </sp-table-cell>
+        </sp-table-row>
+        <sp-table-row value="row3">
+            <sp-table-cell></sp-table-cell>
+            <sp-table-cell>
+                <sp-button static="white" style="--mod-bold-font-weight:400">Screen reader</sp-button>
+            </sp-table-cell>
+            <sp-table-cell>
+                    <sp-button static="white" style="--mod-bold-font-weight:400">This manual testing ensures that the visual information on the screen 
+                    is properly conveyed and read correctly by screen readers such as JAWS, VoiceOver, and NVDA.</sp-button>
+            </sp-table-cell>
+            <sp-table-cell>
+            <sp-button id="trigger-4" variant="secondary" style="--mod-button-background-color-default: #9ef0f0;">Manually Tested</sp-button>
+            <sp-overlay trigger="trigger-4@hover" placement="bottom">
+                <sp-tooltip>
+                    A human has manually tested this component, e.g. screen reader testing.
+                </sp-tooltip>
+            </sp-overlay>
+            </sp-table-cell>
+        </sp-table-row>
+    </sp-table-body>
+</sp-table>

projects/documentation/content/shell-start.njk

@@ -27,6 +27,7 @@ permalink: 'shell-start.html'
             <sp-tabs selected="examples" direction="horizontal">
                 <sp-tab value="examples" label="Examples"></sp-tab>
                 <sp-tab value="api" label="API"></sp-tab>
+                <sp-tab value="accessibility" label="Accessibility"></sp-tab>
             </sp-tabs>
             <div class="parts">
                 <helper class="shell-remove-after"></helper>

projects/documentation/scripts/component-template-parts.js

@@ -254,3 +254,35 @@ tags:
 ---
 ${body}`;
 }
+
+export function accessibilityDestinationTemplate(
+    componentName,
+    componentHeading
+) {
+    return `---
+layout: accessibility.njk
+title: '${nameToTitle(componentName)} API: Spectrum Web Components'
+displayName: ${nameToTitle(componentName)}
+componentName: ${componentName}
+componentHeading: ${componentHeading}
+tags:
+- component-accessibility
+---`;
+}
+
+export function accessibilityPartialTemplate(
+    componentName,
+    componentHeading,
+    body
+) {
+    return `---
+layout: partial.njk
+title: '${nameToTitle(componentName)}: Spectrum Web Components'
+displayName: ${nameToTitle(componentName)}
+componentName: ${componentName}
+partType: accessibility
+tags:
+- ${componentName}
+---
+${body}`;
+}

projects/documentation/scripts/copy-component-docs.js

@@ -15,6 +15,8 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 
 import {
+    accessibilityDestinationTemplate,
+    accessibilityPartialTemplate,
     apiDestinationTemplate,
     apiPartialTemplate,
     exampleDestinationTemplate,
@@ -73,10 +75,9 @@ export async function processREADME(mdPath) {
         return;
     }
     const packageName = extractPackageNameRegExp.exec(mdPath)[1];
-    let componentName =
-        fileName !== 'README.md'
-            ? fileName.replace('.md', '')
-            : extractPackageNameRegExp.exec(mdPath)[1];
+    let componentName = !['README.md', 'accessibility.md'].includes(fileName)
+        ? fileName.replace('.md', '')
+        : extractPackageNameRegExp.exec(mdPath)[1];
     const parent =
         fileName === 'README.md' ? 'root' : packageName + '-children';
     let componentHeading = componentName;
@@ -160,20 +161,45 @@ export async function processREADME(mdPath) {
     }
     const tagType = isComponent ? 'component-examples' : 'tool-examples';
     const body = fs.readFileSync(mdPath);
-    fs.writeFileSync(
-        exampleDestinationFile,
-        exampleDestinationTemplate(
+    if (fileName === 'accessibility.md') {
+        const accessibilityDestinationFile = path.resolve(
+            destinationPath,
             componentName,
-            componentHeading,
-            tagType,
-            parent,
-            packageName
-        )
-    );
-    fs.writeFileSync(
-        examplePartialFile,
-        examplePartialTemplate(componentName, componentHeading, body)
-    );
+            'accessibility.md'
+        );
+        const accessibilityPartialFile = path.resolve(
+            destinationPath,
+            componentName,
+            'accessibility-content.md'
+        );
+        fs.writeFileSync(
+            accessibilityDestinationFile,
+            accessibilityDestinationTemplate(componentName, componentHeading)
+        );
+        fs.writeFileSync(
+            accessibilityPartialFile,
+            accessibilityPartialTemplate(
+                componentName,
+                componentHeading,
+                fs.readFileSync(mdPath, 'utf8')
+            )
+        );
+    } else {
+        fs.writeFileSync(
+            exampleDestinationFile,
+            exampleDestinationTemplate(
+                componentName,
+                componentHeading,
+                tagType,
+                parent,
+                packageName
+            )
+        );
+        fs.writeFileSync(
+            examplePartialFile,
+            examplePartialTemplate(componentName, componentHeading, body)
+        );
+    }
     const hasArgs = fs.existsSync(
         path.resolve(
             __dirname,
@@ -210,6 +236,7 @@ export async function processREADME(mdPath) {
     }export default {
     hasDemoControls: ${hasArgs},
     hasDemoTemplate: ${hasTemplate},
+    isComponentTemplate: ${isComponent},
     deprecationNotice: ${JSON.stringify(deprecationNotice)},
     ${hasArgs ? 'demoControls: Object.values(argTypes),' : ''}
 };