Core: Significantly improve Storybook's own accessibility

MIGRATION.md

@@ -8,6 +8,13 @@
     - [Require `tsconfig.json` `moduleResolution` set to value that supports `types` condition](#require-tsconfigjson-moduleresolution-set-to-value-that-supports-types-condition)
     - [`core.builder` configuration must be a fully resolved path](#corebuilder-configuration-must-be-a-fully-resolved-path)
     - [Removed x-only builtin tags](#removed-x-only-builtin-tags)
+  - [API and Component Changes](#api-and-component-changes)
+    - [Button Component API Changes](#button-component-api-changes)
+      - [Added: ariaLabel](#added-arialabel)
+      - [Added: shortcut](#added-shortcut)
+      - [Added: tooltip](#added-tooltip)
+      - [Removed: active](#removed-active)
+    - [IconButton is deprecated](#iconbutton-is-deprecated)
 - [From version 8.x to 9.0.0](#from-version-8x-to-900)
   - [Core Changes and Removals](#core-changes-and-removals)
     - [Dropped support for legacy packages](#dropped-support-for-legacy-packages)
@@ -26,8 +33,8 @@
     - [Viewport/Backgrounds Addon synchronized configuration and `globals` usage](#viewportbackgrounds-addon-synchronized-configuration-and-globals-usage)
     - [Storysource Addon removed](#storysource-addon-removed)
     - [Mdx-gfm Addon removed](#mdx-gfm-addon-removed)
-  - [API and Component Changes](#api-and-component-changes)
-    - [Button Component API Changes](#button-component-api-changes)
+  - [API and Component Changes](#api-and-component-changes-1)
+    - [Button Component API Changes](#button-component-api-changes-1)
     - [Icon System Updates](#icon-system-updates)
     - [Sidebar Component Changes](#sidebar-component-changes)
     - [Story Store API Changes](#story-store-api-changes)
@@ -585,6 +592,39 @@ export const core = {
 During development of Storybook [Tags](https://storybook.js.org/docs/writing-stories/tags), we created `dev-only`, `docs-only`, and `test-only` built-in tags. These tags were never documented and superseded by the currently-documented `dev`, `autodocs`, and `test` tags which provide more precise control. The outdated `x-only` tags are removed in 10.0.
 During development of Storybook [Tags](https://storybook.js.org/docs/writing-stories/tags), we created `dev-only`, `docs-only`, and `test-only` built-in tags. These tags were never documented and superceded by the currently-documented `dev`, `autodocs`, and `test` tags which provide more precise control. The outdated `x-only` tags are removed in 10.0.
 
+### API and Component Changes
+
+#### Button Component API Changes
+
+##### Added: ariaLabel
+The Button component now has a mandatory `ariaLabel` prop, to ensure that Storybook UI code is accessible to screenreader users.
+
+When buttons have text content as children, and when that text content does not rely on visual context to be understood, you may pass `false` to the `ariaLabel` prop to indicate that an ARIA label is not necessary.
+
+In every other case (your Button only contains an icon, has a responsive layout that can hide its text, or relies on visual context to make sense), you must pass a label to `ariaLabel`, which screenreaders will read. The label should be short and start with an action verb.
+
+##### Added: shortcut
+
+An optional `shortcut` prop was added for internal use. When `shortcut` is set, the Button will be appended with a human-readable string for the shortcut, and the `aria-keyshortcuts` prop will be set.
+
+##### Added: tooltip
+
+Button now displays a tooltip whenever `ariaLabel` or `shortcut` is set. The tooltip can be customised by passing a string to the optional `tooltip` prop.
+
+##### Removed: active
+
+The `active` prop was removed from Button.
+
+The Button component has historically been used to implement Toggle and Select interactions. When you need a Button to have an active state, use ToggleButton if the active state denotes that a state or feature is enabled after pressing the Button.
+
+Use Select if the active state denotes that the Button is open while a selection is being made, or that the Button currently has a selected value.
+
+#### IconButton is deprecated
+
+The IconButton component is deprecated, as it overlaps with Button. Instead, use Button with the `'ghost'` variant and `'small'` padding, and add an `ariaLabel` prop for screenreaders to announce.
+
+IconButton will be removed in future versions.
+
 ## From version 8.x to 9.0.0
 
 ### Core Changes and Removals

code/addons/a11y/src/components/A11YPanel.tsx

@@ -181,7 +181,7 @@ export const A11YPanel: React.FC = () => {
                   accessibility tests manually.
                 </p>
               </div>
-              <Button size="medium" onClick={handleManual}>
+              <Button ariaLabel={false} size="medium" onClick={handleManual}>
                 Run accessibility scan
               </Button>
               <p>
@@ -208,7 +208,7 @@ export const A11YPanel: React.FC = () => {
                       : JSON.stringify(error, null, 2)}
                 </p>
               </div>
-              <Button size="medium" onClick={handleManual}>
+              <Button ariaLabel={false} size="medium" onClick={handleManual}>
                 Rerun accessibility scan
               </Button>
             </>
@@ -222,7 +222,7 @@ export const A11YPanel: React.FC = () => {
                   test manually.
                 </p>
               </div>
-              <Button size="medium" onClick={handleManual}>
+              <Button ariaLabel={false} size="medium" onClick={handleManual}>
                 Run accessibility scan
               </Button>
             </>

code/addons/a11y/src/components/Report/Details.tsx

@@ -123,7 +123,7 @@ const CopyButton = ({ onClick }: { onClick: () => void }) => {
   }, [onClick]);
 
   return (
-    <Button onClick={handleClick}>
+    <Button ariaLabel={false} onClick={handleClick}>
       {copied ? <CheckIcon /> : <CopyIcon />} {copied ? 'Copied' : 'Copy link'}
     </Button>
   );
@@ -163,7 +163,7 @@ export const Details = ({ id, item, type, selection, handleSelectionChange }: De
             return (
               <Fragment key={key}>
                 <Tabs.Trigger value={key} asChild>
-                  <Item variant="ghost" size="medium" id={key}>
+                  <Item ariaLabel={false} variant="ghost" size="medium" id={key}>
                     {index + 1}. {node.html}
                   </Item>
                 </Tabs.Trigger>
@@ -203,7 +203,7 @@ function getContent(node: EnhancedNodeResult) {
       </Messages>
 
       <Actions>
-        <Button onClick={() => handleJumpToElement(node.target.toString())}>
+        <Button ariaLabel={false} onClick={() => handleJumpToElement(node.target.toString())}>
           <LocationIcon /> Jump to element
         </Button>
         <CopyButton onClick={() => handleCopyLink(node.linkPath)} />

code/addons/a11y/src/components/Report/Report.tsx

@@ -1,7 +1,7 @@
 import type { ComponentProps, FC } from 'react';
 import React from 'react';
 
-import { Badge, EmptyTabContent, IconButton } from 'storybook/internal/components';
+import { Badge, Button, EmptyTabContent } from 'storybook/internal/components';
 
 import { ChevronSmallDownIcon } from '@storybook/icons';
 
@@ -121,14 +121,16 @@ export const Report: FC<ReportProps> = ({
                 </Badge>
               )}
               <Count>{item.nodes.length}</Count>
-              <IconButton
+              <Button
                 onClick={(event) => toggleOpen(event, type, item)}
-                aria-label={`${selection ? 'Collapse' : 'Expand'} details for ${title}`}
+                ariaLabel={`${selection ? 'Collapse' : 'Expand'} details for: ${title}`}
                 aria-expanded={!!selection}
                 aria-controls={detailsId}
+                variant="ghost"
+                padding="small"
               >
                 <Icon style={{ transform: `rotate(${selection ? -180 : 0}deg)` }} />
-              </IconButton>
+              </Button>
             </HeaderBar>
             {selection ? (
               <Details

code/addons/a11y/src/components/Tabs.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react';
 
-import { IconButton, ScrollArea, TooltipNote, WithTooltip } from 'storybook/internal/components';
+import { Button, ScrollArea } from 'storybook/internal/components';
 
 import { CollapseIcon, ExpandAltIcon, EyeCloseIcon, EyeIcon, SyncIcon } from '@storybook/icons';
 
@@ -73,7 +73,7 @@ const ActionsWrapper = styled.div({
   gap: 6,
 });
 
-const ToggleButton = styled(IconButton)({
+const CollapsibleButton = styled(Button)({
   // 193px is the total width of the action buttons when the label is visible
   '@container (max-width: 193px)': {
     span: {
@@ -134,43 +134,43 @@ export const Tabs: React.FC<TabsProps> = ({ tabs }) => {
           ))}
         </TabsWrapper>
         <ActionsWrapper>
-          <WithTooltip
-            as="div"
-            hasChrome={false}
-            placement="top"
-            tooltip={<TooltipNote note="Highlight elements with accessibility violations" />}
-            trigger="hover"
-          >
-            <ToggleButton onClick={toggleHighlight} active={highlighted}>
-              {highlighted ? <EyeCloseIcon /> : <EyeIcon />}
-              <span>{highlighted ? 'Hide highlights' : 'Show highlights'}</span>
-            </ToggleButton>
-          </WithTooltip>
-          <WithTooltip
-            as="div"
-            hasChrome={false}
-            placement="top"
-            tooltip={<TooltipNote note={allExpanded ? 'Collapse all' : 'Expand all'} />}
-            trigger="hover"
-          >
-            <IconButton
-              onClick={allExpanded ? handleCollapseAll : handleExpandAll}
-              aria-label={allExpanded ? 'Collapse all' : 'Expand all'}
+          {highlighted ? (
+            <CollapsibleButton
+              onClick={toggleHighlight}
+              ariaLabel="Hide accessibility test result highlights"
+              tooltip="Hide accessibility test result highlights"
             >
-              {allExpanded ? <CollapseIcon /> : <ExpandAltIcon />}
-            </IconButton>
-          </WithTooltip>
-          <WithTooltip
-            as="div"
-            hasChrome={false}
-            placement="top"
-            tooltip={<TooltipNote note="Rerun the accessibility scan" />}
-            trigger="hover"
+              <EyeCloseIcon />
+              <span>Hide highlights</span>
+            </CollapsibleButton>
+          ) : (
+            <CollapsibleButton
+              onClick={toggleHighlight}
+              variant="ghost"
+              ariaLabel="Highlight elements with accessibility test results"
+              tooltip="Highlight elements with accessibility test results"
+            >
+              <EyeIcon />
+              <span>Show highlights</span>
+            </CollapsibleButton>
+          )}
+          <Button
+            variant="ghost"
+            padding="small"
+            onClick={allExpanded ? handleCollapseAll : handleExpandAll}
+            ariaLabel={allExpanded ? 'Collapse all results' : 'Expand all results'}
+            aria-expanded={allExpanded}
+          >
+            {allExpanded ? <CollapseIcon /> : <ExpandAltIcon />}
+          </Button>
+          <Button
+            variant="ghost"
+            padding="small"
+            onClick={handleManual}
+            ariaLabel="Rerun accessibility scan"
           >
-            <IconButton onClick={handleManual} aria-label="Rerun accessibility scan">
-              <SyncIcon />
-            </IconButton>
-          </WithTooltip>
+            <SyncIcon />
+          </Button>
         </ActionsWrapper>
       </Subnav>
       <ScrollArea vertical horizontal>

code/addons/a11y/src/components/VisionSimulator.tsx

@@ -1,7 +1,6 @@
-import type { ReactNode } from 'react';
 import React, { useState } from 'react';
 
-import { IconButton, TooltipLinkList, WithTooltip } from 'storybook/internal/components';
+import { Select } from 'storybook/internal/components';
 
 import { AccessibilityIcon } from '@storybook/icons';
 
@@ -51,79 +50,35 @@ const Hidden = styled.div({
   },
 });
 
-const ColorIcon = styled.span<{ filter: string }>(
+const ColorIcon = styled.span<{ $filter: string }>(
   {
     background: 'linear-gradient(to right, #F44336, #FF9800, #FFEB3B, #8BC34A, #2196F3, #9C27B0)',
     borderRadius: '1rem',
     display: 'block',
     height: '1rem',
     width: '1rem',
   },
-  ({ filter }) => ({
-    filter: getFilter(filter),
+  ({ $filter }) => ({
+    filter: getFilter($filter),
   }),
   ({ theme }) => ({
     boxShadow: `${theme.appBorderColor} 0 0 0 1px inset`,
   })
 );
 
-export interface Link {
-  id: string;
-  title: ReactNode;
-  right?: ReactNode;
-  active: boolean;
-  onClick: () => void;
-}
-
-const Column = styled.span({
-  display: 'flex',
-  flexDirection: 'column',
-});
-
-const Title = styled.span({
-  textTransform: 'capitalize',
-});
-
-const Description = styled.span(({ theme }) => ({
-  fontSize: 11,
-  color: theme.textMutedColor,
-}));
+export const VisionSimulator = () => {
+  const [filter, setFilter] = useState<Filter>(null);
 
-const getColorList = (active: Filter, set: (i: Filter) => void): Link[] => [
-  ...(active !== null
-    ? [
-        {
-          id: 'reset',
-          title: 'Reset color filter',
-          onClick: () => {
-            set(null);
-          },
-          right: undefined,
-          active: false,
-        },
-      ]
-    : []),
-  ...baseList.map((i) => {
-    const description = i.percentage !== undefined ? `${i.percentage}% of users` : undefined;
+  const options = baseList.map(({ name, percentage }) => {
+    const description = percentage !== undefined ? `${percentage}% of users` : undefined;
     return {
-      id: i.name,
-      title: (
-        <Column>
-          <Title>{i.name}</Title>
-          {description && <Description>{description}</Description>}
-        </Column>
-      ),
-      onClick: () => {
-        set(i);
-      },
-      right: <ColorIcon filter={i.name} />,
-      active: active === i,
+      title: name,
+      description,
+      icon: <ColorIcon $filter={name} />,
+      value: name,
     };
-  }),
-];
+  });
 
-export const VisionSimulator = () => {
-  const [filter, setFilter] = useState<Filter>(null);
   return (
     <>
       {filter && (
@@ -135,22 +90,15 @@ export const VisionSimulator = () => {
           }}
         />
       )}
-      <WithTooltip
-        placement="top"
-        tooltip={({ onHide }) => {
-          const colorList = getColorList(filter, (i) => {
-            setFilter(i);
-            onHide();
-          });
-          return <TooltipLinkList links={colorList} />;
-        }}
-        closeOnOutsideClick
-        onDoubleClick={() => setFilter(null)}
-      >
-        <IconButton key="filter" active={!!filter} title="Vision simulator">
-          <AccessibilityIcon />
-        </IconButton>
-      </WithTooltip>
+      <Select
+        resetLabel="Reset color filter"
+        onReset={() => setFilter(null)}
+        icon={<AccessibilityIcon />}
+        ariaLabel="Vision simulator"
+        defaultOptions={filter?.name}
+        options={options}
+        onSelect={(selected) => setFilter(() => ({ name: selected }))}
+      />
       <Hidden>
         <Filters />
       </Hidden>