An open source design system that's fully customizable and agent ready
TypeScript
fix(avatar): decorative when unnamed + no double-announce (obs-9) (#3427)
Cindy Zhangce5d96977271
diff --git a/.changeset/avatar-accessible-name.md b/.changeset/avatar-accessible-name.mdnew file mode 100644index 0000000000..3915005ff7--- /dev/null+++ b/.changeset/avatar-accessible-name.md@@ -0,0 +1,6 @@+---+'@astryxdesign/core': patch+---++[fix] Avatar: an avatar with no `name` or `alt` is now decorative (`role="presentation"` + `aria-hidden`) instead of being announced with the meaningless generic name "Avatar". When named, the inner `<img>` uses an empty `alt` so the accessible name isn't announced twice (once by the `role="img"` wrapper, once by the image) (#3343).+@cixzhangdiff --git a/packages/core/src/Avatar/Avatar.test.tsx b/packages/core/src/Avatar/Avatar.test.tsxnew file mode 100644index 0000000000..fbebf4d0bd--- /dev/null+++ b/packages/core/src/Avatar/Avatar.test.tsx@@ -0,0 +1,37 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, it, expect} from 'vitest';+import {render, screen} from '@testing-library/react';+import {Avatar} from './Avatar';++describe('Avatar', () => {+ it('exposes role="img" with the name as accessible name', () => {+ render(<Avatar name="Ada Lovelace" data-testid="a" />);+ expect(screen.getByRole('img', {name: 'Ada Lovelace'})).toBeInTheDocument();+ });++ it('uses alt over name for the accessible name', () => {+ render(<Avatar name="Ada" alt="Ada Lovelace, profile photo" />);+ expect(+ screen.getByRole('img', {name: 'Ada Lovelace, profile photo'}),+ ).toBeInTheDocument();+ });++ it('is decorative (presentation + aria-hidden) when it has no name or alt (obs-9)', () => {+ render(<Avatar data-testid="a" />);+ const el = screen.getByTestId('a');+ // No meaningful name → not announced as a generic "Avatar".+ expect(el).toHaveAttribute('aria-hidden', 'true');+ expect(el).not.toHaveAttribute('aria-label');+ expect(screen.queryByRole('img')).not.toBeInTheDocument();+ });++ it('does not double-announce: the inner img is decorative when the wrapper is named', () => {+ render(<Avatar name="Ada" src="https://example.com/ada.jpg" />);+ const wrapper = screen.getByRole('img', {name: 'Ada'});+ const innerImg = wrapper.querySelector('img');+ expect(innerImg).not.toBeNull();+ // The inner <img> carries an empty alt so it isn't announced separately.+ expect(innerImg).toHaveAttribute('alt', '');+ });+});diff --git a/packages/core/src/Avatar/Avatar.tsx b/packages/core/src/Avatar/Avatar.tsxindex f79560fb7f..90ef5006ca 100644--- a/packages/core/src/Avatar/Avatar.tsx+++ b/packages/core/src/Avatar/Avatar.tsx@@ -297,7 +297,11 @@ export function Avatar({const showInitials = !showImage && !showFallbackImage && name;const showIcon = !showImage && !showFallbackImage && !name;- const accessibleName = alt || name || 'Avatar';+ // A meaningful accessible name comes from `alt` or `name`. With neither, the+ // avatar is decorative — expose it as `presentation`/`aria-hidden` rather than+ // announcing a meaningless generic "Avatar" (obs-9).+ const accessibleName = alt || name;+ const isDecorative = !accessibleName;const avatarGroup = useAvatarGroup();const resolvedSize = avatarGroup?.size ?? size;const numericSize = useMemo(() => resolveSize(resolvedSize), [resolvedSize]);@@ -306,8 +310,9 @@ export function Avatar({<AvatarSizeContext value={numericSize}><divref={ref}- role="img"- aria-label={accessibleName}+ role={isDecorative ? 'presentation' : 'img'}+ aria-label={isDecorative ? undefined : accessibleName}+ aria-hidden={isDecorative || undefined}data-testid={testId}{...mergeProps(themeProps('avatar', {size: resolvedSize}),@@ -326,7 +331,7 @@ export function Avatar({{showImage && (<imgsrc={src}- alt={accessibleName}+ alt=""onError={() => setImageError(true)}{...stylex.props(styles.image)}/>@@ -334,7 +339,7 @@ export function Avatar({{showFallbackImage && (<imgsrc={fallbackSrc}- alt={accessibleName}+ alt=""onError={() => setFallbackError(true)}{...stylex.props(styles.image)}/>