Skip to content

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.md
new file mode 100644
index 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).
+@cixzhang
diff --git a/packages/core/src/Avatar/Avatar.test.tsx b/packages/core/src/Avatar/Avatar.test.tsx
new file mode 100644
index 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.tsx
index 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}>
<div
ref={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 && (
<img
src={src}
- alt={accessibleName}
+ alt=""
onError={() => setImageError(true)}
{...stylex.props(styles.image)}
/>
@@ -334,7 +339,7 @@ export function Avatar({
{showFallbackImage && (
<img
src={fallbackSrc}
- alt={accessibleName}
+ alt=""
onError={() => setFallbackError(true)}
{...stylex.props(styles.image)}
/>