Skip to content

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.md
new file mode 100644
index 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`).
+@cixzhang
diff --git a/apps/storybook/stories/Icon.stories.tsx b/apps/storybook/stories/Icon.stories.tsx
index 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.mjs
index 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.tsx
index 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.tsx
index 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 span
if (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 (
<IconComponent
ref={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}),