Skip to content

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

TypeScript

fix(lab): a11y minors — Step status text, LogStream live muting, SVGIcon labels, ChatReasoning collapse (#4384)

Baraa Hamodi40065e055a05
diff --git a/.changeset/a11y-lab-minors-i18n.md b/.changeset/a11y-lab-minors-i18n.md
new file mode 100644
index 0000000000..ee221fc917
--- /dev/null
+++ b/.changeset/a11y-lab-minors-i18n.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] i18n: add `@astryx.step.*` catalog keys (`goToStep`, `goToStepWithStatus`, `status.completed`/`status.warning`/`status.error`) backing the lab Stepper's localized status text and clickable-step accessible names.
+@bhamodi
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
index 5ee38041a8..31eb1c6bb4 100644
--- a/packages/core/locales/en.json
+++ b/packages/core/locales/en.json
@@ -879,6 +879,26 @@
"defaultMessage": "Expand all rows",
"description": "Screen-reader-only label on the header expand-all/collapse-all button when at least one row is collapsed (clicking expands every expandable row). Part of the four-way set."
},
+ "@astryx.step.goToStep": {
+ "defaultMessage": "Go to step {stepNumber, number}: {label}",
+ "description": "Accessible name for a clickable step in the lab Stepper. {stepNumber} is the 1-based position, {label} is the step's visible label."
+ },
+ "@astryx.step.goToStepWithStatus": {
+ "defaultMessage": "Go to step {stepNumber, number}: {label}, {status}",
+ "description": "Accessible name for a clickable lab Stepper step that also carries a status. {status} is one of the translated `step.status.*` words (completed/warning/error). Keep the pattern parallel to `step.goToStep`."
+ },
+ "@astryx.step.status.completed": {
+ "defaultMessage": "completed",
+ "description": "Screen-reader-only status word rendered next to a lab Stepper step label when the step is done (either progress-completed or status=success). Lowercase adjective; it is read mid-sentence after the step label."
+ },
+ "@astryx.step.status.warning": {
+ "defaultMessage": "warning",
+ "description": "Screen-reader-only status word rendered next to a lab Stepper step label when status=warning. Lowercase noun/adjective; read mid-sentence after the step label."
+ },
+ "@astryx.step.status.error": {
+ "defaultMessage": "error",
+ "description": "Screen-reader-only status word rendered next to a lab Stepper step label when status=error. Lowercase noun; read mid-sentence after the step label."
+ },
"@astryx.tableTree.collapseRow": {
"defaultMessage": "Collapse row",
"description": "Aria label for the Table tree-data expander chevron when the row is currently expanded."
diff --git a/packages/lab/src/ChatReasoning/ChatReasoning.test.tsx b/packages/lab/src/ChatReasoning/ChatReasoning.test.tsx
index f8223117e3..70861920d7 100644
--- a/packages/lab/src/ChatReasoning/ChatReasoning.test.tsx
+++ b/packages/lab/src/ChatReasoning/ChatReasoning.test.tsx
@@ -53,4 +53,29 @@ describe('ChatReasoning', () => {
render(<ChatReasoning defaultIsExpanded>Content</ChatReasoning>);
expect(screen.getByRole('button')).toHaveAttribute('aria-expanded', 'true');
});
+
+ it('wires the trigger to the content region via aria-controls', () => {
+ render(<ChatReasoning>Full reasoning body</ChatReasoning>);
+ const button = screen.getByRole('button');
+ const controlsId = button.getAttribute('aria-controls');
+ expect(controlsId).toBeTruthy();
+ const region = document.getElementById(controlsId as string);
+ expect(region).not.toBeNull();
+ expect(region).toHaveTextContent('Full reasoning body');
+ });
+
+ it('marks the collapsed content inert and lifts it when expanded', () => {
+ render(<ChatReasoning>Hidden reasoning</ChatReasoning>);
+ const button = screen.getByRole('button');
+ const region = document.getElementById(
+ button.getAttribute('aria-controls') as string,
+ ) as HTMLElement;
+ // Collapsed: visually clipped by the 0fr grid row, so it must also be
+ // removed from the accessibility tree.
+ expect(region).toHaveAttribute('inert');
+ fireEvent.click(button);
+ expect(region).not.toHaveAttribute('inert');
+ fireEvent.click(button);
+ expect(region).toHaveAttribute('inert');
+ });
});
diff --git a/packages/lab/src/ChatReasoning/ChatReasoning.tsx b/packages/lab/src/ChatReasoning/ChatReasoning.tsx
index d0eec729ab..1fa0cbfa2b 100644
--- a/packages/lab/src/ChatReasoning/ChatReasoning.tsx
+++ b/packages/lab/src/ChatReasoning/ChatReasoning.tsx
@@ -15,7 +15,7 @@
* Expandable on click.
*/
-import {useState, useCallback, type ReactNode} from 'react';
+import {useCallback, useId, useState, type ReactNode} from 'react';
import type {BaseProps} from '@astryxdesign/core';
import * as stylex from '@stylexjs/stylex';
import {
@@ -245,6 +245,7 @@ export function ChatReasoning(props: ChatReasoningProps) {
const [internalExpanded, setInternalExpanded] = useState(defaultIsExpanded);
const isControlled = controlledExpanded !== undefined;
const isExpanded = isControlled ? controlledExpanded : internalExpanded;
+ const contentId = useId();
const toggle = useCallback(() => {
const next = !isExpanded;
@@ -272,6 +273,7 @@ export function ChatReasoning(props: ChatReasoningProps) {
role="button"
tabIndex={0}
aria-expanded={isExpanded}
+ aria-controls={contentId}
onClick={toggle}
onKeyDown={e => {
if (e.key === 'Enter' || e.key === ' ') {
@@ -310,6 +312,12 @@ export function ChatReasoning(props: ChatReasoningProps) {
</div>
<div
+ id={contentId}
+ // Collapsed content is only clipped visually (0fr grid row + overflow
+ // hidden), which leaves it in the accessibility tree. `inert` removes
+ // it from AT and the tab order while keeping the element rendered, so
+ // the grid-template-rows expand/collapse transition still runs.
+ inert={!isExpanded}
{...stylex.props(styles.content, isExpanded && styles.contentExpanded)}>
<div {...stylex.props(styles.contentInner)}>
<div {...stylex.props(styles.contentPadding)}>{children}</div>
diff --git a/packages/lab/src/LogStream/LogStream.doc.mjs b/packages/lab/src/LogStream/LogStream.doc.mjs
index b0d4ba6d30..b2ab931a05 100644
--- a/packages/lab/src/LogStream/LogStream.doc.mjs
+++ b/packages/lab/src/LogStream/LogStream.doc.mjs
@@ -11,7 +11,7 @@ export const docs = {
usage: {
description:
- 'Experimental streaming log viewer: mono grid rows (timestamp | level | source | message) with token-derived level accents, expandable per-row detail panels, follow-scroll live tailing with a "Jump to latest" affordance, and an always-dark terminal variant. Appended rows fade in via @starting-style.',
+ 'Experimental streaming log viewer: mono grid rows (timestamp | level | source | message) with token-derived level accents, expandable per-row detail panels, follow-scroll live tailing with a "Jump to latest" affordance, and an always-dark terminal variant. Appended rows fade in via @starting-style. Live announcements follow the pinning state: the role="log" region is aria-live="polite" only while following the tail, and aria-live="off" while unfollowed, so a busy stream never floods assistive tech.',
},
props: [
diff --git a/packages/lab/src/LogStream/LogStream.test.tsx b/packages/lab/src/LogStream/LogStream.test.tsx
index 7d1310a579..68105f75bd 100644
--- a/packages/lab/src/LogStream/LogStream.test.tsx
+++ b/packages/lab/src/LogStream/LogStream.test.tsx
@@ -223,6 +223,31 @@ describe('LogStream', () => {
expect(scroller.scrollTop).toBe(1000);
});
+ it('mutes live announcements while unfollowed and restores them while following (controlled)', () => {
+ const {rerender} = render(
+ <LogStream entries={ENTRIES} isFollowing={false} />,
+ );
+ const log = screen.getByRole('log');
+ expect(log).toHaveAttribute('aria-live', 'off');
+ rerender(<LogStream entries={ENTRIES} isFollowing />);
+ expect(log).toHaveAttribute('aria-live', 'polite');
+ });
+
+ it('unmutes the live region when "Jump to latest" resumes following (uncontrolled)', () => {
+ render(<LogStream entries={ENTRIES} maxHeight={200} />);
+ const log = screen.getByRole('log');
+ // Initially unpinned — the stream must not announce.
+ expect(log).toHaveAttribute('aria-live', 'off');
+ // Scroll away from the tail so the "Jump to latest" affordance appears.
+ setScrollMetrics(log, {scrollHeight: 1000, clientHeight: 200});
+ log.scrollTop = 100;
+ fireEvent.scroll(log);
+ expect(log).toHaveAttribute('aria-live', 'off');
+ // Re-pinning restores polite announcements.
+ fireEvent.click(screen.getByRole('button', {name: /jump to latest/i}));
+ expect(log).toHaveAttribute('aria-live', 'polite');
+ });
+
it('renderEntry replaces the default row', () => {
render(
<LogStream
diff --git a/packages/lab/src/LogStream/LogStream.tsx b/packages/lab/src/LogStream/LogStream.tsx
index 400905b23c..5b2475c366 100644
--- a/packages/lab/src/LogStream/LogStream.tsx
+++ b/packages/lab/src/LogStream/LogStream.tsx
@@ -329,6 +329,10 @@ const LEVEL_STYLE_TERMINAL: Record<LogStreamLevel, stylex.StyleXStyles> = {
* polling; rows use `content-visibility: auto` for offscreen skip but are
* NOT virtualized (window large streams in the caller).
*
+ * Live announcements are tied to follow pinning: the `role="log"` region is
+ * `aria-live="polite"` only while following the tail and `aria-live="off"`
+ * while unfollowed, so appends never flood assistive tech.
+ *
* @example
* ```
* <LogStream
@@ -538,6 +542,12 @@ export function LogStream({
ref={scrollerRef}
role="log"
aria-label={label}
+ // role="log" is implicitly aria-live="polite" — on a busy stream that
+ // floods assistive tech with every appended row (WCAG 2.2.2 / 4.1.3).
+ // Follow-pinning doubles as the mute switch: while the user is away
+ // from the tail (unfollowed), the region is aria-live="off"; resuming
+ // follow ("Jump to latest") restores polite announcements.
+ aria-live={following ? 'polite' : 'off'}
onScroll={handleScroll}
{...stylex.props(styles.scroller(maxHeight ?? null))}>
{entries.map(entry => (
diff --git a/packages/lab/src/SVGIcon/SVGIcon.test.tsx b/packages/lab/src/SVGIcon/SVGIcon.test.tsx
new file mode 100644
index 0000000000..0be95605aa
--- /dev/null
+++ b/packages/lab/src/SVGIcon/SVGIcon.test.tsx
@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {SVGIcon} from './SVGIcon';
+import {bellIcon} from './icons';
+
+describe('SVGIcon', () => {
+ it('defaults to decorative (aria-hidden) when no accessible name is given', () => {
+ const {container} = render(<SVGIcon icon={bellIcon} />);
+ const svg = container.querySelector('svg');
+ expect(svg).toHaveAttribute('aria-hidden', 'true');
+ expect(svg).not.toHaveAttribute('role');
+ });
+
+ it('respects a consumer aria-label: role="img" and no aria-hidden', () => {
+ render(<SVGIcon icon={bellIcon} aria-label="Notifications" />);
+ const svg = screen.getByRole('img', {name: 'Notifications'});
+ expect(svg).not.toHaveAttribute('aria-hidden');
+ });
+
+ it('respects a consumer aria-labelledby: role="img" and no aria-hidden', () => {
+ render(
+ <>
+ <span id="svg-icon-lbl">Alerts</span>
+ <SVGIcon icon={bellIcon} aria-labelledby="svg-icon-lbl" />
+ </>,
+ );
+ const svg = screen.getByRole('img', {name: 'Alerts'});
+ expect(svg).not.toHaveAttribute('aria-hidden');
+ });
+
+ it('still lets an explicit aria-hidden from the consumer win', () => {
+ const {container} = render(
+ <SVGIcon icon={bellIcon} aria-label="Notifications" aria-hidden="true" />,
+ );
+ const svg = container.querySelector('svg');
+ expect(svg).toHaveAttribute('aria-hidden', 'true');
+ });
+});
diff --git a/packages/lab/src/SVGIcon/SVGIcon.tsx b/packages/lab/src/SVGIcon/SVGIcon.tsx
index b8d1e3c1e8..0763b03abd 100644
--- a/packages/lab/src/SVGIcon/SVGIcon.tsx
+++ b/packages/lab/src/SVGIcon/SVGIcon.tsx
@@ -32,11 +32,7 @@ import {themeProps} from '@astryxdesign/core/utils';
// =============================================================================
export type SVGIconVariation =
- | 'linear'
- | 'bold'
- | 'twotone'
- | 'bulk'
- | 'broken';
+ 'linear' | 'bold' | 'twotone' | 'bulk' | 'broken';
export type SVGIconSize = 'xsm' | 'sm' | 'md' | 'lg';
export type SVGIconColor =
| 'primary'
@@ -359,11 +355,23 @@ export function SVGIcon({
...(strokeWidth != null ? strokeWidthOverride : undefined),
};
+ // Decorative by default, meaningful when named — mirroring core Icon's
+ // `label` logic. When the consumer passes an accessible name
+ // (aria-label / aria-labelledby), expose the svg as role="img" instead of
+ // hiding it: an aria-hidden element is removed from the accessibility
+ // tree, so its accessible name would be ignored. Spread BEFORE {...props}
+ // so an explicit aria-hidden/role from the consumer always wins.
+ const hasAccessibleName =
+ props['aria-label'] != null || props['aria-labelledby'] != null;
+ const a11yProps = hasAccessibleName
+ ? ({role: 'img'} as const)
+ : ({'aria-hidden': true} as const);
+
return (
<svg
xmlns="http://www.w3.org/2000/svg"
viewBox={viewBox}
- aria-hidden="true"
+ {...a11yProps}
{...mergeProps(
themeProps('svg-icon', {variation, size, color}),
stylex.props(
diff --git a/packages/lab/src/Stepper/Step.tsx b/packages/lab/src/Stepper/Step.tsx
index 7c6a53dcdc..0c35e0a49b 100644
--- a/packages/lab/src/Stepper/Step.tsx
+++ b/packages/lab/src/Stepper/Step.tsx
@@ -31,6 +31,8 @@ import {
import {mergeProps} from '@astryxdesign/core/utils';
import type {BaseProps} from '@astryxdesign/core';
import {Icon} from '@astryxdesign/core/Icon';
+import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';
+import {useTranslator} from '@astryxdesign/core/i18n';
import {useStepperContext} from './StepperContext';
import {themeProps} from '@astryxdesign/core/utils';
import type {StepStatus} from './StepStatus';
@@ -81,6 +83,11 @@ export interface StepProps extends BaseProps<HTMLLIElement> {
* `accent` is color-only. The current (in-progress) step always keeps its
* current-step indicator regardless of `status`. Never recolors the
* connector/track.
+ *
+ * Because the indicator glyphs are decorative (aria-hidden), the status also
+ * reaches assistive technology as text: visually hidden "completed" /
+ * "warning" / "error" next to the label, and composed into the accessible
+ * name of clickable steps.
*/
status?: StepStatus;
/**
@@ -630,6 +637,7 @@ export function Step({
'data-testid': dataTestId,
...rest
}: StepProps) {
+ const t = useTranslator();
const ctx = useStepperContext();
const {
activeStep,
@@ -806,6 +814,36 @@ export function Step({
}
}
+ // Every indicator glyph above is aria-hidden (pure decoration), so the
+ // step's progress/status must also reach assistive tech as text
+ // (WCAG 1.4.1 / 1.3.1). `error`/`warning` announce the semantic status;
+ // `success` and a completed step both announce "completed". The current
+ // step is announced via aria-current="step" instead, and not-started steps
+ // stay silent (the default state needs no qualifier).
+ const statusText: string | null =
+ status === 'error'
+ ? t('@astryx.step.status.error')
+ : status === 'warning'
+ ? t('@astryx.step.status.warning')
+ : status === 'success' || progress === 'completed'
+ ? t('@astryx.step.status.completed')
+ : null;
+
+ // Rendered next to the label: hidden text for static steps, and composed
+ // into the button's accessible name for clickable ones (an aria-label on
+ // the button would otherwise override the hidden text). Two separate keys
+ // rather than string concatenation so translations control the joiner.
+ const statusTextNode =
+ statusText != null ? <VisuallyHidden>{statusText}</VisuallyHidden> : null;
+ const stepAriaLabel =
+ statusText != null
+ ? t('@astryx.step.goToStepWithStatus', {
+ stepNumber: step + 1,
+ label,
+ status: statusText,
+ })
+ : t('@astryx.step.goToStep', {stepNumber: step + 1, label});
+
const hasIndicator = indicator !== 'none';
const isNumber =
hasIndicator &&
@@ -827,6 +865,7 @@ export function Step({
<div {...stylex.props(styles.iconLabelRow)}>
{indicatorNode}
<span {...stylex.props(styles.label, labelColorStyle)}>{label}</span>
+ {statusTextNode}
{isOptional && (
<>
<span {...stylex.props(styles.optionalDot)}>•</span>
@@ -900,6 +939,7 @@ export function Step({
isVertical ? styles.otLabelRowStart : styles.otLabelRowCenter,
)}>
<span {...stylex.props(styles.label, labelColorStyle)}>{label}</span>
+ {statusTextNode}
{isOptional && (
<>
<span {...stylex.props(styles.optionalDot)}>•</span>
@@ -980,7 +1020,7 @@ export function Step({
<button
type="button"
onClick={handleClick}
- aria-label={`Go to step ${step + 1}: ${label}`}
+ aria-label={stepAriaLabel}
{...stylex.props(
styles.otInteractive,
styles.otRowWrap,
@@ -1058,7 +1098,7 @@ export function Step({
<button
type="button"
onClick={handleClick}
- aria-label={`Go to step ${step + 1}: ${label}`}
+ aria-label={stepAriaLabel}
{...stylex.props(
styles.otInteractive,
styles.otColWrap,
@@ -1112,7 +1152,7 @@ export function Step({
<button
type="button"
onClick={handleClick}
- aria-label={`Go to step ${step + 1}: ${label}`}
+ aria-label={stepAriaLabel}
{...stylex.props(
styles.buttonReset,
styles.focusRing,
@@ -1168,7 +1208,7 @@ export function Step({
<button
type="button"
onClick={handleClick}
- aria-label={`Go to step ${step + 1}: ${label}`}
+ aria-label={stepAriaLabel}
{...stylex.props(
styles.buttonReset,
styles.focusRing,
diff --git a/packages/lab/src/Stepper/Stepper.test.tsx b/packages/lab/src/Stepper/Stepper.test.tsx
index 1320f96de1..1f863a793d 100644
--- a/packages/lab/src/Stepper/Stepper.test.tsx
+++ b/packages/lab/src/Stepper/Stepper.test.tsx
@@ -1,7 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, within} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {Stepper} from './Stepper';
import {Step} from './Step';
@@ -95,7 +95,7 @@ describe('Stepper', () => {
</Stepper>,
);
await user.click(
- screen.getByRole('button', {name: 'Go to step 1: Step 1'}),
+ screen.getByRole('button', {name: 'Go to step 1: Step 1, completed'}),
);
expect(handleClick).toHaveBeenCalledWith(0);
});
@@ -156,7 +156,7 @@ describe('Stepper', () => {
</Stepper>,
);
expect(
- screen.queryByRole('button', {name: 'Go to step 1: Step 1'}),
+ screen.queryByRole('button', {name: /Go to step 1: Step 1/}),
).not.toBeInTheDocument();
});
@@ -412,4 +412,85 @@ describe('Stepper', () => {
expect(future.textContent).not.toContain('2');
expect(future.querySelector('svg')).toBeTruthy();
});
+
+ it('exposes progress/status as visually hidden text (indicators are aria-hidden)', () => {
+ render(
+ <Stepper activeStep={2}>
+ <Step step={0} label="Account" data-testid="done" />
+ <Step step={1} label="Payment" status="error" data-testid="failed" />
+ <Step step={2} label="Review" data-testid="current" />
+ <Step step={3} label="Confirm" data-testid="upcoming" />
+ </Stepper>,
+ );
+ // Completed step announces "completed"; error status wins over completion.
+ expect(
+ within(screen.getByTestId('done')).getByText('completed'),
+ ).toBeInTheDocument();
+ expect(
+ within(screen.getByTestId('failed')).getByText('error'),
+ ).toBeInTheDocument();
+ expect(
+ within(screen.getByTestId('failed')).queryByText('completed'),
+ ).not.toBeInTheDocument();
+ // Current step is announced via aria-current, not hidden text; upcoming
+ // steps stay silent.
+ expect(
+ within(screen.getByTestId('current')).queryByText('completed'),
+ ).not.toBeInTheDocument();
+ expect(
+ within(screen.getByTestId('upcoming')).queryByText(
+ /completed|error|warning/,
+ ),
+ ).not.toBeInTheDocument();
+ });
+
+ it('exposes warning and success statuses as visually hidden text', () => {
+ render(
+ <Stepper activeStep={2}>
+ <Step step={0} label="Build" status="warning" data-testid="warned" />
+ <Step step={1} label="Deploy" status="success" data-testid="passed" />
+ </Stepper>,
+ );
+ expect(
+ within(screen.getByTestId('warned')).getByText('warning'),
+ ).toBeInTheDocument();
+ expect(
+ within(screen.getByTestId('passed')).getByText('completed'),
+ ).toBeInTheDocument();
+ });
+
+ it('composes status into the accessible name of clickable steps', () => {
+ render(
+ <Stepper activeStep={2} onStepClick={() => {}}>
+ <Step step={0} label="Account" />
+ <Step step={1} label="Payment" status="error" />
+ <Step step={2} label="Review" />
+ </Stepper>,
+ );
+ expect(
+ screen.getByRole('button', {name: 'Go to step 1: Account, completed'}),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole('button', {name: 'Go to step 2: Payment, error'}),
+ ).toBeInTheDocument();
+ // The current step gets no status suffix (aria-current covers it).
+ expect(
+ screen.getByRole('button', {name: 'Go to step 3: Review'}),
+ ).toBeInTheDocument();
+ });
+
+ it('exposes hidden status text in the on-track layout too', () => {
+ render(
+ <Stepper activeStep={1} indicatorPosition="on-track">
+ <Step step={0} label="Account" data-testid="ot-done" />
+ <Step step={1} label="Payment" data-testid="ot-current" />
+ </Stepper>,
+ );
+ expect(
+ within(screen.getByTestId('ot-done')).getByText('completed'),
+ ).toBeInTheDocument();
+ expect(
+ within(screen.getByTestId('ot-current')).queryByText('completed'),
+ ).not.toBeInTheDocument();
+ });
});