Skip to content

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

TypeScript

fix(core): name labeled Dividers; single Spinner label announcement (#4370)

Baraa Hamodi414c96afbd35
diff --git a/.changeset/a11y-content-minors.md b/.changeset/a11y-content-minors.md
new file mode 100644
index 0000000000..c51a971813
--- /dev/null
+++ b/.changeset/a11y-content-minors.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Divider: expose the label as the separator's accessible name via aria-labelledby; Spinner: name the status element from the visible label instead of duplicating it as aria-label
+@bhamodi
diff --git a/packages/core/src/Chat/ChatSystemMessage.test.tsx b/packages/core/src/Chat/ChatSystemMessage.test.tsx
index e5bafa032f..aaef01d72f 100644
--- a/packages/core/src/Chat/ChatSystemMessage.test.tsx
+++ b/packages/core/src/Chat/ChatSystemMessage.test.tsx
@@ -28,6 +28,11 @@ describe('ChatSystemMessage', () => {
expect(screen.getByText('Today')).toBeTruthy();
});
+ it('exposes the divider variant label as the separator accessible name', () => {
+ render(<ChatSystemMessage variant="divider">Today</ChatSystemMessage>);
+ expect(screen.getByRole('separator')).toHaveAccessibleName('Today');
+ });
+
it('renders icon', () => {
render(
<ChatSystemMessage icon={<span data-testid="icon">*</span>}>
diff --git a/packages/core/src/Divider/Divider.test.tsx b/packages/core/src/Divider/Divider.test.tsx
index 92ee6ee14d..d9d66c45e3 100644
--- a/packages/core/src/Divider/Divider.test.tsx
+++ b/packages/core/src/Divider/Divider.test.tsx
@@ -89,25 +89,49 @@ describe('Divider', () => {
it('renders vertical divider with label', () => {
render(
- <Divider
- orientation="vertical"
- label="Vertical"
- data-testid="divider"
- />,
+ <Divider orientation="vertical" label="Vertical" data-testid="divider" />,
);
const divider = screen.getByTestId('divider');
expect(divider).toHaveAttribute('aria-orientation', 'vertical');
expect(screen.getByText('Vertical')).toBeInTheDocument();
});
- it('renders astryx-* class names for theme targeting', () => {
+ it('exposes the label as the accessible name of the separator', () => {
+ render(<Divider label="Section" data-testid="divider" />);
+ const divider = screen.getByTestId('divider');
+ expect(divider).toHaveAttribute('aria-labelledby');
+ expect(divider).toHaveAccessibleName('Section');
+ });
+
+ it('names the separator from a ReactNode label via aria-labelledby', () => {
+ render(<Divider label={<span>Custom</span>} data-testid="divider" />);
+ expect(screen.getByTestId('divider')).toHaveAccessibleName('Custom');
+ });
+
+ it('does not set aria-labelledby without a label', () => {
+ render(<Divider data-testid="divider" />);
+ expect(screen.getByTestId('divider')).not.toHaveAttribute(
+ 'aria-labelledby',
+ );
+ });
+
+ it('prefers an explicit aria-label over the rendered label', () => {
render(
<Divider
- variant="strong"
- orientation="vertical"
+ label="Section"
+ aria-label="Custom name"
data-testid="divider"
/>,
);
+ const divider = screen.getByTestId('divider');
+ expect(divider).toHaveAccessibleName('Custom name');
+ expect(divider).not.toHaveAttribute('aria-labelledby');
+ });
+
+ it('renders astryx-* class names for theme targeting', () => {
+ render(
+ <Divider variant="strong" orientation="vertical" data-testid="divider" />,
+ );
const root = screen.getByTestId('divider');
expect(root.className).toContain('astryx-divider');
expect(root.className).toContain('strong');
diff --git a/packages/core/src/Divider/Divider.tsx b/packages/core/src/Divider/Divider.tsx
index 57de56980f..5f4911bde9 100644
--- a/packages/core/src/Divider/Divider.tsx
+++ b/packages/core/src/Divider/Divider.tsx
@@ -15,7 +15,7 @@
* - /packages/cli/templates/blocks/components/Divider/ (showcase blocks)
*/
-import type {ReactNode} from 'react';
+import {useId, type ReactNode} from 'react';
import type {BaseProps} from '../BaseProps';
import * as stylex from '@stylexjs/stylex';
@@ -165,9 +165,19 @@ export function Divider({
className,
style,
ref,
+ 'aria-label': ariaLabel,
+ 'aria-labelledby': ariaLabelledBy,
...props
}: DividerProps) {
const isHorizontal = orientation === 'horizontal';
+ const labelId = useId();
+
+ // A separator does not derive its accessible name from its content, so the
+ // rendered label must be referenced explicitly via aria-labelledby to be
+ // exposed as the separator's name (WCAG 1.3.1). An explicit aria-label or
+ // aria-labelledby from the consumer takes precedence.
+ const resolvedLabelledBy =
+ ariaLabelledBy ?? (label && ariaLabel == null ? labelId : undefined);
return (
<div
@@ -175,6 +185,8 @@ export function Divider({
{...props}
role="separator"
aria-orientation={orientation}
+ aria-label={ariaLabel}
+ aria-labelledby={resolvedLabelledBy}
{...mergeProps(
themeProps('divider', {variant, orientation}),
stylex.props(
@@ -196,6 +208,7 @@ export function Divider({
/>
{label && (
<div
+ id={labelId}
{...stylex.props(
labelStyles.label,
!isHorizontal && labelStyles.verticalLabel,
diff --git a/packages/core/src/Spinner/Spinner.test.tsx b/packages/core/src/Spinner/Spinner.test.tsx
index 316e3a42f6..aa52bd4a86 100644
--- a/packages/core/src/Spinner/Spinner.test.tsx
+++ b/packages/core/src/Spinner/Spinner.test.tsx
@@ -64,12 +64,16 @@ describe('Spinner', () => {
);
});
- it('uses string label as aria-label automatically', () => {
+ it('names the status element from the visible string label', () => {
render(<Spinner label="Fetching data" data-testid="spinner" />);
- expect(screen.getByRole('status')).toHaveAttribute(
- 'aria-label',
- 'Fetching data',
- );
+ expect(screen.getByRole('status')).toHaveAccessibleName('Fetching data');
+ });
+
+ it('does not duplicate a visible string label as aria-label', () => {
+ render(<Spinner label="Fetching data" data-testid="spinner" />);
+ const status = screen.getByRole('status');
+ expect(status).not.toHaveAttribute('aria-label');
+ expect(status).toHaveAttribute('aria-labelledby');
});
it('uses explicit aria-label over string label', () => {
@@ -103,9 +107,7 @@ describe('Spinner', () => {
});
it('defaults aria-label to "Loading" for ReactNode label without explicit aria-label', () => {
- render(
- <Spinner label={<span>Rich content</span>} data-testid="spinner" />,
- );
+ render(<Spinner label={<span>Rich content</span>} data-testid="spinner" />);
expect(screen.getByRole('status')).toHaveAttribute('aria-label', 'Loading');
});
diff --git a/packages/core/src/Spinner/Spinner.tsx b/packages/core/src/Spinner/Spinner.tsx
index f3b7aad4ac..61341e5027 100644
--- a/packages/core/src/Spinner/Spinner.tsx
+++ b/packages/core/src/Spinner/Spinner.tsx
@@ -16,7 +16,7 @@
* - /packages/cli/templates/blocks/components/Spinner/ (showcase blocks)
*/
-import {useEffect, useRef, type ReactNode} from 'react';
+import {useEffect, useId, useRef, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {durationVars, spacingVars} from '../theme/tokens.stylex';
import {useTheme} from '../theme/useTheme';
@@ -119,8 +119,9 @@ export interface SpinnerProps extends BaseProps<HTMLSpanElement> {
* Visible content displayed below the spinner.
* Accepts a string or ReactNode for rich content.
*
- * When `label` is a string, it is also used as the accessible name
- * (aria-label) unless `aria-label` is explicitly set.
+ * When `label` is a string, the visible text also provides the accessible
+ * name of the status element (via aria-labelledby, avoiding a duplicate
+ * announcement) unless `aria-label` is explicitly set.
*
* @example
* ```
@@ -255,6 +256,14 @@ export function Spinner({
const {border, diameter} = SIZES[size];
const frameSize = diameter + border * 2;
const hasLabel = label != null;
+ const labelId = useId();
+
+ // When a visible string label renders (and no explicit aria-label is set),
+ // name the status element from the visible Text via aria-labelledby instead
+ // of duplicating the same string as aria-label — the duplicate would be
+ // announced twice by screen readers (WCAG 4.1.2).
+ const namedByVisibleLabel =
+ hasLabel && typeof label === 'string' && ariaLabel == null;
// Resolve accessible name: explicit aria-label > string label > "Loading"
const resolvedAriaLabel =
@@ -264,7 +273,8 @@ export function Spinner({
<span
ref={hasLabel ? undefined : ref}
role="status"
- aria-label={resolvedAriaLabel}
+ aria-label={namedByVisibleLabel ? undefined : resolvedAriaLabel}
+ aria-labelledby={namedByVisibleLabel ? labelId : undefined}
data-testid={hasLabel ? undefined : testId}
{...(hasLabel ? {} : restProps)}
{...mergeProps(
@@ -294,7 +304,7 @@ export function Spinner({
)}>
{spinner}
{typeof label === 'string' ? (
- <Text type="body" weight="bold">
+ <Text id={labelId} type="body" weight="bold">
{label}
</Text>
) : (