Skip to content

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

TypeScript

fix(skeleton): aria-hidden by default + reduced-motion guard (complex-20) (#3421)

Cindy Zhang41ab5feac403
diff --git a/.changeset/skeleton-aria-hidden.md b/.changeset/skeleton-aria-hidden.md
new file mode 100644
index 0000000000..931a9641ff
--- /dev/null
+++ b/.changeset/skeleton-aria-hidden.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Skeleton: the loading placeholder is now `aria-hidden` by default (it's decorative — the surrounding region conveys the loading/busy state) and its pulse animation is disabled under `prefers-reduced-motion: reduce`. The `aria-hidden` default can be overridden by consumers (#3343).
+@cixzhang
diff --git a/packages/core/src/Skeleton/Skeleton.test.tsx b/packages/core/src/Skeleton/Skeleton.test.tsx
new file mode 100644
index 0000000000..f2992c3cdc
--- /dev/null
+++ b/packages/core/src/Skeleton/Skeleton.test.tsx
@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {Skeleton} from './Skeleton';
+
+describe('Skeleton', () => {
+ it('renders a placeholder element', () => {
+ render(<Skeleton width={200} height={20} data-testid="sk" />);
+ expect(screen.getByTestId('sk')).toBeInTheDocument();
+ });
+
+ it('is hidden from assistive tech by default (complex-20)', () => {
+ render(<Skeleton width={200} height={20} data-testid="sk" />);
+ expect(screen.getByTestId('sk')).toHaveAttribute('aria-hidden', 'true');
+ });
+
+ it('allows the aria-hidden default to be overridden', () => {
+ render(
+ <Skeleton width={200} height={20} data-testid="sk" aria-hidden={false} />,
+ );
+ // Consumer opt-out: not hidden when explicitly set false.
+ expect(screen.getByTestId('sk')).toHaveAttribute('aria-hidden', 'false');
+ });
+});
diff --git a/packages/core/src/Skeleton/Skeleton.tsx b/packages/core/src/Skeleton/Skeleton.tsx
index af189cc48e..5ab5c358c1 100644
--- a/packages/core/src/Skeleton/Skeleton.tsx
+++ b/packages/core/src/Skeleton/Skeleton.tsx
@@ -62,7 +62,12 @@ const styles = stylex.create({
animationDirection: 'alternate',
animationDuration: durationVars['--duration-medium-max'],
animationIterationCount: 'infinite',
- animationName: skeletonFade,
+ // Disable the pulse under reduced-motion; the static placeholder still
+ // reads as loading (complex-20).
+ animationName: {
+ default: skeletonFade,
+ '@media (prefers-reduced-motion: reduce)': 'none',
+ },
animationTimingFunction: 'steps(10, end)',
},
});
@@ -180,6 +185,11 @@ export function Skeleton({
return (
<div
ref={ref}
+ // Purely decorative loading placeholder — hide from assistive tech so it
+ // isn't announced as empty content. The surrounding region should convey
+ // the loading/busy state (e.g. aria-busy) (complex-20). Consumers can
+ // override via props if a specific skeleton must be exposed.
+ aria-hidden="true"
data-testid={testId}
{...mergeProps(
themeProps('skeleton'),