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.mdnew file mode 100644index 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.++@bhamodidiff --git a/packages/core/locales/en.json b/packages/core/locales/en.jsonindex 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.mjsindex 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.tsxindex 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 nodediff --git a/packages/core/src/Thumbnail/Thumbnail.tsx b/packages/core/src/Thumbnail/Thumbnail.tsxindex 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.tsxindex 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.mjsindex 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.tsxindex 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<HTMLDivElemendescription?: 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>