An open source design system that's fully customizable and agent ready
TypeScript
feat(Icon): add label prop for accessible name (#4177) (#4193)
Cindy Zhang78a654838e9d
diff --git a/.changeset/icon-label-accessible-name.md b/.changeset/icon-label-accessible-name.mdnew file mode 100644index 0000000000..748078b123--- /dev/null+++ b/.changeset/icon-label-accessible-name.md@@ -0,0 +1,6 @@+---+'@astryxdesign/core': patch+---++[feat] Icon: add an optional `label` prop for the accessible name. Setting it makes a standalone icon meaningful (`role="img"` + `aria-label`, no `aria-hidden`), collapsing the old three-attribute dance into one prop; omitting it (or passing `''`) keeps the decorative default (`aria-hidden`).+@cixzhangdiff --git a/apps/storybook/stories/Icon.stories.tsx b/apps/storybook/stories/Icon.stories.tsxindex 806b9b3b75..c8fb1b261d 100644--- a/apps/storybook/stories/Icon.stories.tsx+++ b/apps/storybook/stories/Icon.stories.tsx@@ -63,6 +63,32 @@ export const Default: Story = {},};+/**+ * Icons are decorative by default (`aria-hidden`), which is correct when+ * adjacent text already conveys the meaning. When an icon stands alone and+ * carries meaning on its own, give it an accessible name with `label` — this+ * exposes it to screen readers as `role="img"` with that name and unhides it.+ */+export const AccessibleName: Story = {+ render: () => (+ <HStack gap={6} vAlign="center">+ <VStack gap={2} hAlign="center">+ <Icon+ icon={CheckCircleIcon}+ color="success"+ size="lg"+ label="Completed"+ />+ <Text type="supporting">Meaningful (label="Completed")</Text>+ </VStack>+ <VStack gap={2} hAlign="center">+ <Icon icon={HomeIcon} color="secondary" size="lg" />+ <Text type="supporting">Decorative (no label)</Text>+ </VStack>+ </HStack>+ ),+};+export const Primary: Story = {args: {icon: HomeIcon,diff --git a/packages/core/src/Icon/Icon.doc.mjs b/packages/core/src/Icon/Icon.doc.mjsindex 1aac1c6cb4..6d536fb449 100644--- a/packages/core/src/Icon/Icon.doc.mjs+++ b/packages/core/src/Icon/Icon.doc.mjs@@ -34,6 +34,11 @@ export const docs = {description: 'Icon size.',default: "'md'",},+ {+ name: 'label',+ type: 'string',+ description: 'Accessible name for a MEANINGFUL, standalone icon (a status glyph or icon-only indicator with no adjacent text). Setting it exposes the icon to screen readers as role="img" with this text as the accessible name (aria-label) and removes the default aria-hidden. Omit it (default) for decorative icons and the icon stays hidden from assistive tech (aria-hidden="true"). This is the accessible-name / alt-text prop for icons — one prop instead of manually setting aria-label + role + aria-hidden. An empty string is treated as decorative. Do not set it when an interactive parent (Button, IconButton, link) already names the control.',+ },],theming: {targets: [@@ -45,6 +50,7 @@ export const docs = {bestPractices: [{ guidance: true, description: 'Use semantic icon names when available; they adapt to theme changes automatically.' },{ guidance: true, description: 'Pair icons with text labels for accessibility; icon-only elements need an accessible label.' },+ { guidance: true, description: 'For a meaningful standalone icon (no adjacent text), give it an accessible name via the `label` prop — it sets role="img" + aria-label and unhides the icon.' },{ guidance: true, description: 'Use color tokens for icon colors, not hardcoded hex values.' },{ guidance: true, description: 'Be mindful of context; decorative icons in compact components can distract rather than help.' },{ guidance: false, description: 'Use icons as the sole means of conveying meaning; always provide a text alternative.' },@@ -79,6 +85,11 @@ export const docsZh = {description: '图标尺寸。',default: "'md'",},+ {+ name: 'label',+ type: 'string',+ description: '有含义的独立图标的可访问名称(无相邻文字的状态图标或纯图标指示器)。设置后会将图标以 role="img" 暴露给辅助技术,并以该文本作为可访问名称(aria-label),同时移除默认的 aria-hidden。省略(默认)用于装饰性图标,图标对辅助技术保持隐藏(aria-hidden="true")。空字符串按装饰性处理。当交互式父元素(Button、IconButton、链接)已命名该控件时请勿设置。',+ },],theming: {targets: [@@ -123,5 +134,6 @@ export const docsDense = {icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',color: 'Color variant mapped to Astryx icon color tokens.',size: 'Icon size.',+ label: 'Accessible name for a meaningful, standalone icon. Sets role="img" + aria-label and drops the default aria-hidden. Omit (default) for decorative icons (stays aria-hidden). Empty string = decorative. The accessible-name/alt-text prop for icons.',},};diff --git a/packages/core/src/Icon/Icon.test.tsx b/packages/core/src/Icon/Icon.test.tsxindex d51eb2f881..7f0d7ccfbb 100644--- a/packages/core/src/Icon/Icon.test.tsx+++ b/packages/core/src/Icon/Icon.test.tsx@@ -183,4 +183,100 @@ describe('Icon', () => {expect(icon).toHaveAttribute('aria-label', 'Done');expect(icon).toHaveAttribute('aria-hidden', 'false');});++ describe('label (accessible name)', () => {+ it('makes a component-mode icon meaningful: role="img" + aria-label, no aria-hidden', () => {+ render(<Icon icon={TestIcon} label="Completed" data-testid="icon" />);+ const icon = screen.getByTestId('icon');+ expect(icon).toHaveAttribute('role', 'img');+ expect(icon).toHaveAttribute('aria-label', 'Completed');+ expect(icon).not.toHaveAttribute('aria-hidden');+ });++ it('makes a string-mode (registry) icon meaningful: role="img" + aria-label, no aria-hidden', () => {+ render(<Icon icon="check" label="Completed" data-testid="icon" />);+ const icon = screen.getByTestId('icon');+ expect(icon).toHaveAttribute('role', 'img');+ expect(icon).toHaveAttribute('aria-label', 'Completed');+ expect(icon).not.toHaveAttribute('aria-hidden');+ });++ it('keeps the decorative default when label is omitted (component mode)', () => {+ render(<Icon icon={TestIcon} data-testid="icon" />);+ const icon = screen.getByTestId('icon');+ expect(icon).toHaveAttribute('aria-hidden', 'true');+ expect(icon).not.toHaveAttribute('role');+ expect(icon).not.toHaveAttribute('aria-label');+ });++ it('keeps the decorative default when label is omitted (string mode)', () => {+ render(<Icon icon="check" data-testid="icon" />);+ const icon = screen.getByTestId('icon');+ expect(icon).toHaveAttribute('aria-hidden', 'true');+ expect(icon).not.toHaveAttribute('role');+ expect(icon).not.toHaveAttribute('aria-label');+ });++ it('treats an empty string label as decorative (component mode)', () => {+ render(<Icon icon={TestIcon} label="" data-testid="icon" />);+ const icon = screen.getByTestId('icon');+ expect(icon).toHaveAttribute('aria-hidden', 'true');+ expect(icon).not.toHaveAttribute('role');+ expect(icon).not.toHaveAttribute('aria-label');+ });++ it('treats an empty string label as decorative (string mode)', () => {+ render(<Icon icon="check" label="" data-testid="icon" />);+ const icon = screen.getByTestId('icon');+ expect(icon).toHaveAttribute('aria-hidden', 'true');+ expect(icon).not.toHaveAttribute('role');+ expect(icon).not.toHaveAttribute('aria-label');+ });++ it('lets an explicit aria-hidden win over label (component mode)', () => {+ render(+ <Icon icon={TestIcon} label="Close" aria-hidden data-testid="icon" />,+ );+ const icon = screen.getByTestId('icon');+ expect(icon).toHaveAttribute('aria-hidden', 'true');+ });++ it('lets an explicit aria-hidden win over label (string mode)', () => {+ render(+ <Icon icon="check" label="Close" aria-hidden data-testid="icon" />,+ );+ const icon = screen.getByTestId('icon');+ expect(icon).toHaveAttribute('aria-hidden', 'true');+ });++ it('lets an explicit aria-label override the label-derived name (component mode)', () => {+ render(+ <Icon+ icon={TestIcon}+ label="Close"+ aria-label="Dismiss"+ data-testid="icon"+ />,+ );+ expect(screen.getByTestId('icon')).toHaveAttribute(+ 'aria-label',+ 'Dismiss',+ );+ });++ it('lets an explicit role override the label-derived role (string mode)', () => {+ render(+ <Icon+ icon="check"+ label="Close"+ role="presentation"+ data-testid="icon"+ />,+ );+ expect(screen.getByTestId('icon')).toHaveAttribute(+ 'role',+ 'presentation',+ );+ });+ });});diff --git a/packages/core/src/Icon/Icon.tsx b/packages/core/src/Icon/Icon.tsxindex bd0d7bb0ba..695305f719 100644--- a/packages/core/src/Icon/Icon.tsx+++ b/packages/core/src/Icon/Icon.tsx@@ -214,6 +214,50 @@ export interface IconProps extends Omit<* @default 'md'*/size?: IconSize;+ /**+ * Accessible name for the icon. Set this only when the icon is MEANINGFUL on+ * its own — a standalone status glyph or an icon-only indicator with no+ * adjacent text conveying the same information. Providing it exposes the icon+ * to assistive tech as `role="img"` with this string as the accessible name+ * (via `aria-label`) and drops the default `aria-hidden="true"`.+ *+ * Omit it (the default) for decorative icons — the common case, e.g. an icon+ * beside a text label — and the icon stays hidden from assistive tech+ * (`aria-hidden="true"`). An empty string (`''`) is treated the same as+ * omitting it (decorative), since an empty accessible name is meaningless.+ *+ * Don't set `label` when an interactive parent (Button, IconButton, link)+ * already names the control — that produces a duplicate announcement.+ *+ * @example+ * ```+ * // Meaningful, standalone icon+ * <Icon icon="success" label="Completed" />+ *+ * // Decorative icon (default) — omit label+ * <Icon icon="search" />+ * ```+ */+ label?: string;+}++/**+ * Derives the ARIA attributes for an icon from its `label` prop.+ *+ * - Non-empty `label` → meaningful image: `role="img"` + `aria-label`, and no+ * `aria-hidden` (an `aria-hidden` element is removed from the accessibility+ * tree, so its accessible name would be ignored).+ * - Omitted or empty `label` → decorative default: `aria-hidden="true"`.+ *+ * The result is spread BEFORE `{...props}` in both render modes so an explicit+ * `aria-hidden` / `role` / `aria-label` from the consumer always wins.+ */+function getIconA11yProps(+ label: string | undefined,+): {role: 'img'; 'aria-label': string} | {'aria-hidden': 'true'} {+ return label != null && label !== ''+ ? {role: 'img', 'aria-label': label}+ : {'aria-hidden': 'true'};}// =============================================================================@@ -232,9 +276,14 @@ export function Icon({icon,color = 'inherit',size = 'md',+ label,ref,...props}: IconProps) {+ // Derive ARIA from `label`: decorative (aria-hidden) by default, or a+ // meaningful image (role="img" + aria-label) when `label` is non-empty.+ const a11yProps = getIconA11yProps(label);+// String mode: resolve from icon registry, wrap in styled spanif (typeof icon === 'string') {return (@@ -242,6 +291,7 @@ export function Icon({name={icon}color={color}size={size}+ a11yProps={a11yProps}spanProps={props}/>);@@ -252,7 +302,10 @@ export function Icon({return (<IconComponentref={ref}- aria-hidden="true"+ // Derived a11y (decorative default or meaningful `label`) is spread+ // BEFORE {...props} so an explicit aria-hidden/role/aria-label from the+ // consumer still wins as an escape hatch.+ {...a11yProps}{...mergeProps(themeProps('icon', {size, color}),stylex.props(styles.root, colorStyles[color], sizeStyles[size]),@@ -279,11 +332,13 @@ function IconFromRegistry({name,color,size,+ a11yProps,spanProps,}: {name: IconName;color: IconColor;size: IconSize;+ a11yProps: {role: 'img'; 'aria-label': string} | {'aria-hidden': 'true'};spanProps?: Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'>;}) {const resolvedIcon = getIcon(name);@@ -294,11 +349,11 @@ function IconFromRegistry({return (<span- // Decorative by default, but placed BEFORE the prop spread so consumers- // can override it (e.g. `aria-hidden={false}` + `role="img"` +- // `aria-label`) to expose a meaningful standalone icon. This matches- // component-mode Icon, which already sets aria-hidden before its spread.- aria-hidden="true"+ // Derived a11y — decorative (aria-hidden) by default, or a meaningful+ // image (role="img" + aria-label) when `label` is set. Placed BEFORE the+ // prop spread so consumers can still override it with explicit+ // aria-hidden/role/aria-label. This mirrors component-mode Icon.+ {...a11yProps}{...(spanProps as React.HTMLAttributes<HTMLSpanElement>)}{...mergeProps(themeProps('icon', {size, color}),