Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(core): explicit decorative handling for unnamed Thumbnail images (#4001)

Baraa Hamodid80987321743
diff --git a/.changeset/thumbnail-decorative-alt.md b/.changeset/thumbnail-decorative-alt.md
new file mode 100644
index 0000000000..7d23f61ac9
--- /dev/null
+++ b/.changeset/thumbnail-decorative-alt.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Thumbnail/TopNavMegaMenuFeaturedCard: images without alt text are now explicitly decorative instead of silently empty-alt, matching Avatar's handling.
+
+@bhamodi
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
index 1141104369..885653efc1 100644
--- a/packages/core/locales/en.json
+++ b/packages/core/locales/en.json
@@ -775,6 +775,10 @@
"defaultMessage": "Open {accessibleName}",
"description": "\"Open\" = launch/reveal (not \"unfold\" or the adjective). Screen-reader-only name on a clickable Thumbnail — example: `Open Sunset photo`."
},
+ "@astryx.thumbnail.fallbackName": {
+ "defaultMessage": "Thumbnail",
+ "description": "Generic screen-reader name for a Thumbnail (image preview) that has no `alt` or `label`. Last-resort fallback so the control is never nameless; prefer a real name via `alt` or `label`."
+ },
"@astryx.timeInput.clearLabel": {
"defaultMessage": "Clear {label}",
"description": "Screen-reader-only label on the X that clears the value from a TimeInput. Example: `Clear Start time`."
diff --git a/packages/core/src/Thumbnail/Thumbnail.doc.mjs b/packages/core/src/Thumbnail/Thumbnail.doc.mjs
index 18b051eb19..f30408c089 100644
--- a/packages/core/src/Thumbnail/Thumbnail.doc.mjs
+++ b/packages/core/src/Thumbnail/Thumbnail.doc.mjs
@@ -16,7 +16,7 @@ export const docs = {
{
name: 'alt',
type: 'string',
- description: 'Alt text for the image.',
+ description: 'Alt text for the image. When omitted, the image is explicitly decorative (alt="", role="presentation", aria-hidden) and hidden from screen readers; a dev warning fires if neither alt nor label is set.',
},
{
name: 'label',
@@ -102,7 +102,7 @@ export const docs = {
export const docsZh = {
propDescriptions: {
src: '\u56FE\u7247\u6E90 URL\u3002',
- alt: '\u56FE\u7247\u7684\u66FF\u4EE3\u6587\u672C\u3002',
+ alt: '\u56FE\u7247\u7684\u66FF\u4EE3\u6587\u672C\u3002\u7701\u7565\u65F6\u56FE\u7247\u4F1A\u88AB\u663E\u5F0F\u6807\u8BB0\u4E3A\u88C5\u9970\u6027\uFF08alt=""\u3001role="presentation"\u3001aria-hidden\uFF09\u5E76\u5BF9\u5C4F\u5E55\u9605\u8BFB\u5668\u9690\u85CF\uFF1B\u82E5 alt \u548C label \u5747\u672A\u8BBE\u7F6E\uFF0C\u5F00\u53D1\u73AF\u5883\u4F1A\u53D1\u51FA\u8B66\u544A\u3002',
label: '\u65E0\u969C\u788D\u6807\u7B7E\uFF08\u5982\u6587\u4EF6\u540D\uFF09\u3002\u60AC\u505C\u65F6\u4EE5\u63D0\u793A\u5DE5\u5177\u663E\u793A\u3002',
onRemove: '\u8986\u76D6\u5C42\u79FB\u9664\u6309\u94AE\u7684\u56DE\u8C03\u3002',
onClick: '\u70B9\u51FB\u5904\u7406\u5668\u3002\u6DFB\u52A0\u6309\u94AE\u8BED\u4E49\u548C\u60AC\u505C\u9634\u5F71\u3002',
@@ -143,7 +143,7 @@ export const docsDense = {
},
propDescriptions: {
src: 'Image source URL.',
- alt: 'Alt text for image.',
+ alt: 'Alt text for image. Omitted → explicitly decorative (alt="" + role="presentation" + aria-hidden); dev warn when src set with no alt and no label.',
label: 'Accessible label (file name). Tooltip on hover, aria-label.',
onRemove: '(e) => void. Overlaid remove button callback.',
onClick: '(e) => void. Adds button semantics + hover shadow.',
diff --git a/packages/core/src/Thumbnail/Thumbnail.test.tsx b/packages/core/src/Thumbnail/Thumbnail.test.tsx
index 83b6da0432..5cf4ab48f2 100644
--- a/packages/core/src/Thumbnail/Thumbnail.test.tsx
+++ b/packages/core/src/Thumbnail/Thumbnail.test.tsx
@@ -78,6 +78,41 @@ describe('Thumbnail', () => {
).toBeInTheDocument();
});
+ it('marks the image as explicitly decorative when no alt is provided', () => {
+ render(
+ <Thumbnail src="/photo.jpg" label="photo.png" data-testid="thumb" />,
+ );
+ const img = screen.getByTestId('thumb').querySelector('img');
+ expect(img).toHaveAttribute('alt', '');
+ expect(img).toHaveAttribute('role', 'presentation');
+ expect(img).toHaveAttribute('aria-hidden', 'true');
+ // The image must not be exposed to assistive technology as a nameless img.
+ expect(screen.queryByRole('img')).toBeNull();
+ });
+
+ it('exposes the image with normal img semantics when alt is provided', () => {
+ render(<Thumbnail src="/photo.jpg" alt="Vacation photo" />);
+ const img = screen.getByRole('img', {name: 'Vacation photo'});
+ expect(img).not.toHaveAttribute('role');
+ expect(img).not.toHaveAttribute('aria-hidden');
+ });
+
+ it('warns once when src is set with no alt and no label', () => {
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ render(<Thumbnail src="/photo.jpg" />);
+ expect(warnSpy).toHaveBeenCalledTimes(1);
+ expect(warnSpy.mock.calls[0][0]).toContain('Thumbnail');
+ warnSpy.mockRestore();
+ });
+
+ it('does not warn when the thumbnail is named via label or alt', () => {
+ const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ render(<Thumbnail src="/a.jpg" label="a.png" />);
+ render(<Thumbnail src="/b.jpg" alt="Photo b" />);
+ expect(warnSpy).not.toHaveBeenCalled();
+ warnSpy.mockRestore();
+ });
+
it('label is shown via tooltip, not as inline text', () => {
render(<Thumbnail label="photo.png" data-testid="thumb" />);
// Label should exist in DOM (tooltip) but not as a direct child text node
diff --git a/packages/core/src/Thumbnail/Thumbnail.tsx b/packages/core/src/Thumbnail/Thumbnail.tsx
index 022e42069a..af5d8f8b02 100644
--- a/packages/core/src/Thumbnail/Thumbnail.tsx
+++ b/packages/core/src/Thumbnail/Thumbnail.tsx
@@ -13,6 +13,10 @@
* Uses useImageMode (APCA) to detect image luminance so the overlaid
* remove button always has sufficient contrast.
*
+ * Images without `alt` are explicitly decorative (alt="" +
+ * role="presentation" + aria-hidden, matching Avatar). A dev-time warning
+ * fires once when `src` is set with no `alt` and no other name source.
+ *
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Thumbnail/Thumbnail.doc.mjs
* - /packages/core/src/Thumbnail/Thumbnail.test.tsx
@@ -21,6 +25,7 @@
* - /packages/cli/templates/blocks/components/Thumbnail/ (showcase blocks)
*/
+import {useEffect, useRef} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
colorVars,
@@ -55,7 +60,14 @@ export interface ThumbnailProps extends BaseProps<HTMLDivElement> {
*/
src?: string;
/**
- * Alt text for the image. Required for accessibility when `src` is provided.
+ * Alt text for the image.
+ *
+ * When omitted, the image is explicitly decorative (`alt=""` +
+ * `role="presentation"` + `aria-hidden`, matching Avatar) and hidden from
+ * assistive technology. Provide `alt` whenever the image conveys content;
+ * without it, screen reader users only hear the `label` (file name), or a
+ * generic "thumbnail" if `label` is also missing — which triggers a
+ * dev-time warning.
*/
alt?: string;
/**
@@ -289,12 +301,49 @@ export function Thumbnail({
const showPlaceholder = !isLoading && !hasSrc;
const isInteractive = onClick != null && !isDisabled && !isLoading;
const accessibleName =
- label && alt ? `${label} — ${alt}` : (label ?? alt ?? 'thumbnail');
+ label && alt
+ ? `${label} — ${alt}`
+ : (label ?? alt ?? t('@astryx.thumbnail.fallbackName'));
+
+ // Without `alt`, the image is explicitly decorative rather than silently
+ // empty-alt, matching Avatar's handling of unnamed images.
+ const isImageDecorative = !alt;
+
+ // Dev-time guardrail: `src` with no `alt` hides the image from assistive
+ // technology. That is fine when the thumbnail is otherwise named — `label`
+ // (or a consumer-provided aria name) becomes the group's accessible name —
+ // but with no name source at all the group falls back to a generic
+ // "thumbnail". Warn once per component instance (in an effect) rather than
+ // on every render.
+ const hasNameSource =
+ alt != null ||
+ label != null ||
+ props['aria-label'] != null ||
+ props['aria-labelledby'] != null;
+ const warnedUnnamedImageRef = useRef(false);
+ useEffect(() => {
+ if (hasSrc && !hasNameSource && !warnedUnnamedImageRef.current) {
+ warnedUnnamedImageRef.current = true;
+ console.warn(
+ 'Thumbnail: `src` is set without `alt` or `label`. The image is ' +
+ 'treated as decorative and hidden from assistive technology, and ' +
+ 'the thumbnail falls back to a generic "thumbnail" name. Pass ' +
+ '`alt` to describe the image content, or `label` (file name) to ' +
+ 'name the thumbnail.',
+ );
+ }
+ }, [hasSrc, hasNameSource]);
const imageContent = (
<>
{showImage && (
- <img src={src} alt={alt ?? ''} {...stylex.props(styles.image)} />
+ <img
+ src={src}
+ alt={alt ?? ''}
+ role={isImageDecorative ? 'presentation' : undefined}
+ aria-hidden={isImageDecorative || undefined}
+ {...stylex.props(styles.image)}
+ />
)}
{showSkeleton && <Skeleton radius={2} />}
{showPlaceholder && (
diff --git a/packages/core/src/TopNav/TopNav.test.tsx b/packages/core/src/TopNav/TopNav.test.tsx
index dc8b4e2d93..3b7d2337be 100644
--- a/packages/core/src/TopNav/TopNav.test.tsx
+++ b/packages/core/src/TopNav/TopNav.test.tsx
@@ -523,4 +523,49 @@ describe('TopNavItem', () => {
expect(card).toHaveAttribute('aria-label', 'Featured');
});
});
+
+ describe('TopNavMegaMenuFeaturedCard image alt handling', () => {
+ it('marks the image as explicitly decorative when imageAlt is omitted', () => {
+ render(
+ <TopNavMegaMenuFeaturedCard
+ title="What's new"
+ image="/promo.jpg"
+ data-testid="featured-card"
+ />,
+ );
+ const img = screen.getByTestId('featured-card').querySelector('img');
+ expect(img).toHaveAttribute('alt', '');
+ expect(img).toHaveAttribute('role', 'presentation');
+ expect(img).toHaveAttribute('aria-hidden', 'true');
+ // The image must not be exposed to assistive technology as a nameless img.
+ expect(screen.queryByRole('img')).toBeNull();
+ });
+
+ it('exposes the image with normal img semantics when imageAlt is provided', () => {
+ render(
+ <TopNavMegaMenuFeaturedCard
+ title="What's new"
+ image="/promo.jpg"
+ imageAlt="Team collaboration"
+ />,
+ );
+ const img = screen.getByRole('img', {name: 'Team collaboration'});
+ expect(img).not.toHaveAttribute('role');
+ expect(img).not.toHaveAttribute('aria-hidden');
+ });
+
+ it('keeps title and link semantics unchanged with a decorative image', () => {
+ render(
+ <TopNavMegaMenuFeaturedCard
+ title="What's new"
+ image="/promo.jpg"
+ linkLabel="Read the announcement"
+ linkHref="/blog/v4"
+ />,
+ );
+ expect(screen.getByText("What's new")).toBeInTheDocument();
+ const link = screen.getByRole('link', {name: /Read the announcement/});
+ expect(link).toHaveAttribute('href', '/blog/v4');
+ });
+ });
});
diff --git a/packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.doc.mjs b/packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.doc.mjs
index 2d6e39ef05..aee11c310d 100644
--- a/packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.doc.mjs
+++ b/packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.doc.mjs
@@ -27,7 +27,7 @@ export const docs = {
{
name: 'imageAlt',
type: 'string',
- description: 'Alt text for the image.',
+ description: 'Alt text for the image. When omitted, the image is explicitly decorative (alt="", role="presentation", aria-hidden) — usually correct since the card already has a visible title. Provide it only when the image conveys information beyond the title and description.',
},
{
name: 'linkLabel',
@@ -71,7 +71,7 @@ export const docsZh = {
{
name: 'imageAlt',
type: 'string',
- description: '图片的替代文本。',
+ description: '图片的替代文本。省略时图片会被显式标记为装饰性(alt=""、role="presentation"、aria-hidden)——由于卡片已有可见标题,这通常是正确的。仅当图片传达标题和描述之外的信息时才提供。',
},
{
name: 'linkLabel',
@@ -99,7 +99,7 @@ export const docsDense = {
title: 'Card title.',
description: 'Description below title.',
image: 'Image URL above body.',
- imageAlt: 'Image alt text.',
+ imageAlt: 'Image alt text. Omitted → explicitly decorative (hidden from screen readers); usually correct since card has visible title.',
linkLabel: 'CTA link text.',
linkHref: 'CTA link URL.',
children: 'Custom content below standard body.',
diff --git a/packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.tsx b/packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.tsx
index 5c3ea0deea..1479a43cc9 100644
--- a/packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.tsx
+++ b/packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.tsx
@@ -84,7 +84,15 @@ export interface TopNavMegaMenuFeaturedCardProps extends BaseProps<HTMLDivElemen
description?: string;
/** Optional image URL displayed above the body. */
image?: string;
- /** Alt text for the image. */
+ /**
+ * Alt text for the image.
+ *
+ * When omitted, the image is explicitly decorative (`alt=""` +
+ * `role="presentation"` + `aria-hidden`, matching Avatar) and hidden from
+ * assistive technology. Since the card already has a visible `title`, a
+ * decorative image is usually correct; pass `imageAlt` only when the image
+ * conveys information beyond the title and description.
+ */
imageAlt?: string;
/** CTA link text. */
linkLabel?: string;
@@ -149,7 +157,16 @@ export function TopNavMegaMenuFeaturedCard({
)}
{...rest}>
{image && (
- <img src={image} alt={imageAlt ?? ''} {...stylex.props(styles.image)} />
+ // Without `imageAlt`, the image is explicitly decorative rather than
+ // silently empty-alt, matching Avatar's handling of unnamed images.
+ // Usually correct here: the card already has a visible title.
+ <img
+ src={image}
+ alt={imageAlt ?? ''}
+ role={imageAlt ? undefined : 'presentation'}
+ aria-hidden={imageAlt ? undefined : true}
+ {...stylex.props(styles.image)}
+ />
)}
<div {...stylex.props(styles.body)}>
<span {...stylex.props(styles.title)}>{title}</span>