An open source design system that's fully customizable and agent ready
TypeScript
fix(Button): a tooltip that repeats the accessible name adds no description (#9681)
Cindy Zhangbec12a3b2e2c
diff --git a/.changeset/button-tooltip-name-echo.md b/.changeset/button-tooltip-name-echo.mdnew file mode 100644index 0000000000..f3c9dac42c--- /dev/null+++ b/.changeset/button-tooltip-name-echo.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] Button, IconButton: a tooltip that repeated the button's accessible name was also added as its description, so screen readers read the same words twice ("Close, button, Close"). Astryx's own close, pagination, copy and collapse buttons did this by default. Now a tooltip whose trimmed text equals the accessible name still shows, but adds no description, when Button can read that name: its `aria-label`, or its label when any icon or end content is a decorative Icon. A tooltip that says more, or a Button named another way (`aria-labelledby`, or text in its icon or end content), keeps the description.++@cixzhangdiff --git a/docs/specs/components/Button/Button.spec.md b/docs/specs/components/Button/Button.spec.mdindex f915b54b42..abd2f106d4 100644--- a/docs/specs/components/Button/Button.spec.md+++ b/docs/specs/components/Button/Button.spec.md@@ -128,7 +128,7 @@ Consumer migration instructions belong in consumer docs and release notes.| FR9 | Busy-only (pending, not disabled, not interruptible): Button exposes `aria-disabled="true"`, keeps its tab stop, renders no native `disabled`, and keeps full opacity. Pointer activation is cancelled and does not reach ancestor click handlers; Enter and Space are suppressed; other keys still reach the caller's `onKeyDown`. A link-mode Button stays a link while busy-only. | `spec:AST-085` FR1, FR2, FR6; current source and tests || FR10 | Disabled (`isDisabled`, or a disabled enclosing ButtonGroup) MUST stay focusable with `aria-disabled="true"`, keep its tab stop and focus, apply FR9's guards, never run `onClick` or `clickAction`, and paint at half opacity. Disabled wins over pending: a disabled, loading Button shows the Spinner and `aria-busy` but follows this row. Implementation gap: only a disabled Button with a `tooltip` renders this shape; without a tooltip it renders native `disabled`, which removes it from the tab order and drops focus when it becomes disabled. | `family:buttons` FR3; `spec:AST-085`; current source and tests || FR11 | With `href` and not disabled, Button renders the link component resolved from `as`, then `LinkProvider`, then a native anchor, with `target` and `rel`, full button styling, and no text decoration. Destination handling follows `family:navigation-destinations`. A disabled Button with `href` renders a `<button>` that follows FR10 and never navigates. Implementation gap: a focused link Button that becomes disabled is replaced by that new `<button>`, so focus falls to the page with or without a `tooltip`; without a `tooltip` the `<button>` also carries native `disabled` (FR10). | `family:navigation-destinations` FR1–FR7; current source and tests |-| FR12 | With `tooltip`, the tooltip attaches to the Button element itself (no wrapper element), opens above it, and its content is added to `aria-describedby` after any caller value. | Current source; real-browser accessibility test |+| FR12 | With `tooltip`, the tooltip attaches to the Button element itself (no wrapper element), opens above it, and its content is added to `aria-describedby` after any caller value, unless its trimmed text equals the Button's accessible name as its props decide it (the derived or caller `aria-label`, or `label` when `icon` and `endContent` render nothing or a decorative Icon), as Avatar AR5 does, so a tooltip that repeats the name is not read twice. When the name comes from elsewhere (`aria-labelledby`, or other content in `icon` or `endContent`), the tooltip still describes the Button. IconButton inherits this. | Current source; real-browser accessibility test || FR13 | A standalone Button paints the shadow token for its `elevation`. Inside a ButtonGroup it paints no shadow and reflects `data-elevation="none"`, whatever `elevation` says. | `family:buttons` FR8–FR10; current source and tests || FR14 | The root carries `astryx-button` and reflects the effective `data-variant`, `data-size`, and `data-elevation`. | `family:buttons` FR10; `architecture:component-theming-surface`; tests || FR15 | Hover paints the shared interaction overlay on hover-capable pointers, and a press paints the shared pressed overlay through the press controller: at once under a mouse or a pen (`spec:AST-094` FR11's fine-pointer profile) and on FR11's control profile under a finger, fading out over 200 ms on release at `tempo` 1, scaled by the theme's `tempo` (`spec:AST-108` FR4). Without a reduced-motion preference, a standalone Button also scales to 0.98 on a mouse press, or while the touch press reads on; under reduced motion it MUST NOT scale (`design:reduced-motion` DR1). All of this paint follows the element's exposed disabled state: a Button that is natively disabled or exposes `aria-disabled="true"` (busy-only, disabled with a tooltip, or a caller's own `aria-disabled`) shows no overlay and no press scale, even when it stays operable. Inside a ButtonGroup the press scale does not apply. Button's hover and press transitions are fast, and instant under reduced motion. Implementation gap: the 0.98 press scale also applies under reduced motion; only its transition becomes instant. | Current source and tests; `spec:AST-094` FR11 and DEC-21 for the mouse and pen press |diff --git a/docs/specs/components/IconButton/IconButton.spec.md b/docs/specs/components/IconButton/IconButton.spec.mdindex 6d1928268e..22fe92d5bd 100644--- a/docs/specs/components/IconButton/IconButton.spec.md+++ b/docs/specs/components/IconButton/IconButton.spec.md@@ -124,7 +124,7 @@ mode, width, tooltip) is Button's, with Button's defaults.substitutes for it (`family:buttons` FR1).- **AR2 — Visible hint.** IconButton shows no visible text. A visible hintexists only when the caller sets `tooltip`, which also describes the button- (`component:Button` FR12).+ unless it repeats the `label` (`component:Button` FR12).- **AR3 — Target size.** With the default square aspect, the smallestIconButton with no `width` is 28 by 28 CSS pixels, above the WCAG 2.5.8 24 by24 minimum. A caller `width` or theme icon-only aspect that narrows it belowdiff --git a/packages/core/src/Banner/Banner.test.tsx b/packages/core/src/Banner/Banner.test.tsxindex 87c98ae9f0..78ab2c1a9c 100644--- a/packages/core/src/Banner/Banner.test.tsx+++ b/packages/core/src/Banner/Banner.test.tsx@@ -157,9 +157,17 @@ describe('Banner', () => {expect(getComputedStyle(button).getPropertyValue('--color-text-primary'),).toBe(expectedRole);- const tooltip = document.getElementById(- button.getAttribute('aria-describedby')!,- );+ // A tooltip that repeats the name does not describe the button+ // (Button FR12), so find it by its text.+ const describedBy = button.getAttribute('aria-describedby');+ const tooltip =+ describedBy != null+ ? document.getElementById(describedBy)+ : (screen+ .getAllByRole('tooltip', {hidden: true})+ .find(+ el => el.textContent === button.getAttribute('aria-label'),+ ) ?? null);expect(tooltip).not.toBeNull();expect(getComputedStyle(tooltip!).getPropertyValue('--color-text-primary'),@@ -830,7 +838,13 @@ describe('Banner', () => {<Banner status="info" title={<span>Rich title</span>} isDismissable />,);const button = screen.getByRole('button', {name: 'Dismiss'});- expect(button).toHaveAccessibleDescription('Dismiss');+ // The tooltip repeats the name, so it shows but adds no description.+ expect(button).not.toHaveAttribute('aria-describedby');+ expect(+ screen+ .getAllByRole('tooltip', {hidden: true})+ .some(el => el.textContent === 'Dismiss'),+ ).toBe(true);});it('uses a translated dismissLabel for a rich title and its tooltip', () => {@@ -845,7 +859,12 @@ describe('Banner', () => {const button = screen.getByRole('button', {name: 'Wartungshinweis schließen',});- expect(button).toHaveAccessibleDescription('Wartungshinweis schließen');+ expect(button).not.toHaveAttribute('aria-describedby');+ expect(+ screen+ .getAllByRole('tooltip', {hidden: true})+ .some(el => el.textContent === 'Wartungshinweis schließen'),+ ).toBe(true);});it('keeps a translated verb when the titled message falls back to English', () => {diff --git a/packages/core/src/Button/Button.test.tsx b/packages/core/src/Button/Button.test.tsxindex a0e85b59c9..e18fa6efea 100644--- a/packages/core/src/Button/Button.test.tsx+++ b/packages/core/src/Button/Button.test.tsx@@ -21,6 +21,7 @@ import {} from '@testing-library/react';import userEvent from '@testing-library/user-event';import {Button} from './Button';+import {Icon} from '../Icon/Icon';import * as stylex from '@stylexjs/stylex';import {hasPressedArm,@@ -490,6 +491,101 @@ describe('Button', () => {expect(screen.getByRole('button')).toHaveAttribute('type', 'submit');});+ describe('tooltip as description (FR12)', () => {+ it('describes the button by a tooltip that adds to its name', () => {+ render(<Button label="Save" tooltip="Save your changes" />);+ const button = screen.getByRole('button', {name: 'Save'});+ expect(button).toHaveAccessibleDescription('Save your changes');+ });++ it('adds no description when the tooltip repeats the visible name', () => {+ render(<Button label="Close" tooltip=" Close " />);+ const button = screen.getByRole('button', {name: 'Close'});+ expect(button).not.toHaveAttribute('aria-describedby');+ });++ it('adds no description when an icon-only tooltip repeats its label', () => {+ render(+ <Button+ label="Close"+ tooltip="Close"+ icon={<span>x</span>}+ isIconOnly+ />,+ );+ const button = screen.getByRole('button', {name: 'Close'});+ expect(button).not.toHaveAttribute('aria-describedby');+ });++ it('keeps a caller description when the tooltip repeats the name', () => {+ render(+ <>+ <span id="hint">Closes the panel</span>+ <Button label="Close" tooltip="Close" aria-describedby="hint" />+ </>,+ );+ const button = screen.getByRole('button', {name: 'Close'});+ expect(button).toHaveAttribute('aria-describedby', 'hint');+ });++ it('keeps the description when aria-labelledby names the button', () => {+ render(+ <>+ <span id="close-name">Close the editor</span>+ <Button+ label="Close"+ tooltip="Close"+ icon={<span>x</span>}+ isIconOnly+ aria-labelledby="close-name"+ />+ </>,+ );+ const button = screen.getByRole('button', {name: 'Close the editor'});+ expect(button).toHaveAccessibleDescription('Close');+ });++ it('adds no description when a decorative Icon sits beside a repeated label', () => {+ render(+ <Button label="Edit" icon={<Icon icon="close" />} tooltip="Edit" />,+ );+ const button = screen.getByRole('button', {name: 'Edit'});+ expect(button).not.toHaveAttribute('aria-describedby');+ });++ it('adds no description when a decorative Icon ends a repeated label', () => {+ render(+ <Button+ label="Sort"+ endContent={<Icon icon="close" />}+ tooltip="Sort"+ />,+ );+ const button = screen.getByRole('button', {name: 'Sort'});+ expect(button).not.toHaveAttribute('aria-describedby');+ });++ it('keeps the description when endContent adds to the name', () => {+ render(+ <Button+ label="Messages"+ tooltip="Messages"+ endContent={<span>3</span>}+ />,+ );+ const button = screen.getByRole('button', {name: 'Messages 3'});+ expect(button).toHaveAccessibleDescription('Messages');+ });++ it('compares with a caller aria-label, not the visible text', () => {+ render(+ <Button label="Clear" aria-label="Clear Search" tooltip="Clear" />,+ );+ const button = screen.getByRole('button', {name: 'Clear Search'});+ expect(button).toHaveAccessibleDescription('Clear');+ });+ });+it('uses aria-disabled instead of disabled when tooltip is present and button is disabled', () => {render(<Button label="Test" tooltip="Reason disabled" isDisabled />);const button = screen.getByRole('button');diff --git a/packages/core/src/Button/Button.tsx b/packages/core/src/Button/Button.tsxindex 5fba526295..86bf661c3c 100644--- a/packages/core/src/Button/Button.tsx+++ b/packages/core/src/Button/Button.tsx@@ -19,6 +19,7 @@*/import {+ isValidElement,use,useEffect,useRef,@@ -44,6 +45,7 @@ import {focusVars,} from '../theme/tokens.stylex';import {Spinner} from '../Spinner/Spinner';+import {Icon} from '../Icon/Icon';import {VisuallyHidden} from '../VisuallyHidden/VisuallyHidden';import {IconDefaultSizeProvider} from '../Icon/IconDefaultSizeContext';import {iconBoxSizeStyles, type IconSize} from '../Icon/IconSize.stylex';@@ -559,6 +561,21 @@ const groupStyles = stylex.create({},});+/**+ * Whether `node` adds nothing to a content name: nothing renders, or an Icon+ * with no label. Any other node can add text.+ */+function addsNoName(node: ReactNode): boolean {+ if (!isRenderable(node)) {+ return true;+ }+ if (!isValidElement<{label?: unknown}>(node) || node.type !== Icon) {+ return false;+ }+ const {label} = node.props;+ return typeof label !== 'string' || label.trim() === '';+}+/*** A versatile button component with multiple variants.*@@ -836,10 +853,29 @@ export function Button({(children != null && children !== label);const ariaLabelProp = needsAriaLabel ? {'aria-label': label} : null;+ // The Button's accessible name when props decide it: the derived+ // aria-label, else a caller aria-label, else the label text alone. It is+ // not known here when a caller aria-labelledby names the Button from other+ // elements, or when `icon` or `endContent` can add text to its content+ // name (a count, for example). A decorative Icon in either slot adds none.+ const accessibleName =+ props['aria-labelledby'] != null+ ? undefined+ : needsAriaLabel+ ? label+ : (props['aria-label'] ??+ (addsNoName(icon) && addsNoName(endContent) ? label : undefined));+ // A tooltip that repeats the name adds nothing to the description, so a+ // screen reader does not read the same words twice.+ const isTooltipName =+ tooltip != null &&+ accessibleName != null &&+ tooltip.trim() === accessibleName.trim();+// When a tooltip is attached via the hook, point aria-describedby at the// tooltip content (composing with any consumer-provided value).const describedByProp =- tooltip != null+ tooltip != null && !isTooltipName? {'aria-describedby':[props['aria-describedby'], tooltipHook.describedBy]diff --git a/packages/core/src/CodeBlock/CodeBlock.test.tsx b/packages/core/src/CodeBlock/CodeBlock.test.tsxindex ce57449aad..1b35808862 100644--- a/packages/core/src/CodeBlock/CodeBlock.test.tsx+++ b/packages/core/src/CodeBlock/CodeBlock.test.tsx@@ -213,9 +213,14 @@ describe('CodeBlock', () => {// Theme seam: a design system can restyle the copy control via this class// without turning the button off and re-implementing it.expect(copyButton).toHaveClass('astryx-code-block-copy-button');- // The button carries a visible "Copy code" hover/focus hint (tooltip),- // wired through aria-describedby — a bare <button> could not.- expect(copyButton).toHaveAttribute('aria-describedby');+ // The button carries a visible "Copy code" hover/focus hint (tooltip). It+ // repeats the name, so it adds no description (Button FR12).+ expect(+ screen+ .getAllByRole('tooltip', {hidden: true})+ .some(el => el.textContent === 'Copy code'),+ ).toBe(true);+ expect(copyButton).not.toHaveAttribute('aria-describedby');});it('keeps the copy button tooltip as "Copy code" after copying', async () => {diff --git a/packages/core/src/Pagination/Pagination.test.tsx b/packages/core/src/Pagination/Pagination.test.tsxindex d3727e54d1..7459deebb7 100644--- a/packages/core/src/Pagination/Pagination.test.tsx+++ b/packages/core/src/Pagination/Pagination.test.tsx@@ -145,24 +145,22 @@ describe('Pagination', () => {it('gives the prev/next carets a hover tooltip matching their accessible name', () => {// The carets are icon-only, so sighted users need a visible label on// hover, not just the accessible name. The tooltip reuses the same- // localized string, so it is reachable via aria-describedby.+ // localized string, so it adds no description (Button FR12).render(<Pagination page={3} onChange={() => {}} totalPages={5} />);const prev = screen.getByRole('button', {name: 'Go to previous page'});const next = screen.getByRole('button', {name: 'Go to next page'});- const tooltips = screen.getAllByRole('tooltip', {hidden: true});- const tooltipIds = new Set(tooltips.map(el => el.id));expect(- prev- .getAttribute('aria-describedby')- ?.split(' ')- .some(id => tooltipIds.has(id)),+ screen+ .getAllByRole('tooltip', {hidden: true})+ .some(el => el.textContent === 'Go to previous page'),).toBe(true);expect(- next- .getAttribute('aria-describedby')- ?.split(' ')- .some(id => tooltipIds.has(id)),+ screen+ .getAllByRole('tooltip', {hidden: true})+ .some(el => el.textContent === 'Go to next page'),).toBe(true);+ expect(prev).not.toHaveAttribute('aria-describedby');+ expect(next).not.toHaveAttribute('aria-describedby');});it('renders the prev/next caret icons without an extra mirror wrapper span', () => {