Skip to content

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

TypeScript

feat(core): add VisuallyHidden accessibility primitive (#3381)

Cindy Zhang5393708d367d
diff --git a/.changeset/visually-hidden.md b/.changeset/visually-hidden.md
new file mode 100644
index 0000000000..af4e8dd72a
--- /dev/null
+++ b/.changeset/visually-hidden.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Add `VisuallyHidden` — an accessibility primitive that renders content in the accessibility tree while hiding it visually. Use for accessible names on icon-only controls, `aria-live` announcement regions, and supplementary screen-reader context. Renders a `<span>` by default; use `as` for block/live-region elements (#3338).
+@cixzhang
diff --git a/apps/storybook/stories/VisuallyHidden.stories.tsx b/apps/storybook/stories/VisuallyHidden.stories.tsx
new file mode 100644
index 0000000000..22829c47f3
--- /dev/null
+++ b/apps/storybook/stories/VisuallyHidden.stories.tsx
@@ -0,0 +1,100 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import type {Meta, StoryObj} from '@storybook/react';
+import {useState} from 'react';
+import {VisuallyHidden} from '@astryxdesign/core/VisuallyHidden';
+import {Button} from '@astryxdesign/core/Button';
+import {Card} from '@astryxdesign/core/Card';
+import {Section} from '@astryxdesign/core/Section';
+import {VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+
+const meta: Meta<typeof VisuallyHidden> = {
+ title: 'Core/VisuallyHidden',
+ component: VisuallyHidden,
+ tags: ['autodocs'],
+ argTypes: {
+ children: {
+ control: 'text',
+ description: 'Content exposed to assistive technology while hidden',
+ },
+ as: {
+ control: 'text',
+ description: "HTML tag to render as (default 'span')",
+ },
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof VisuallyHidden>;
+
+export const Default: Story = {
+ args: {
+ children: 'This text is only announced to screen readers',
+ },
+ render: args => (
+ <Section variant="muted">
+ <Card>
+ <VStack gap={3}>
+ <Text type="body">
+ There is visually-hidden text below this line. Inspect the DOM or
+ use a screen reader to perceive it.
+ </Text>
+ <VisuallyHidden {...args} />
+ <Text type="body" color="secondary">
+ (nothing visible renders between the two paragraphs)
+ </Text>
+ </VStack>
+ </Card>
+ </Section>
+ ),
+};
+
+export const SupplementaryContext: Story = {
+ render: () => (
+ <Section variant="muted">
+ <Card>
+ <VStack gap={2} align="start">
+ <Text type="body">
+ Read more{' '}
+ <a href="https://example.com">
+ here
+ <VisuallyHidden> about accessibility primitives</VisuallyHidden>
+ </a>
+ </Text>
+ <Text type="body" color="secondary">
+ The link is announced as “here about accessibility primitives”, so
+ it is not an ambiguous “here” out of context.
+ </Text>
+ </VStack>
+ </Card>
+ </Section>
+ ),
+};
+
+export const LiveRegion: Story = {
+ render: () => <LiveRegionDemo />,
+};
+
+function LiveRegionDemo() {
+ const [count, setCount] = useState(0);
+ return (
+ <Section variant="muted">
+ <Card>
+ <VStack gap={3} align="start">
+ <Text type="body">
+ Activating the button updates a polite live region that a screen
+ reader announces.
+ </Text>
+ <Button label="Add item" onClick={() => setCount(c => c + 1)} />
+ <Text type="body" color="secondary">
+ Items added: {count}
+ </Text>
+ <VisuallyHidden as="div" role="status" aria-live="polite">
+ {count > 0 ? `${count} item${count === 1 ? '' : 's'} added` : ''}
+ </VisuallyHidden>
+ </VStack>
+ </Card>
+ </Section>
+ );
+}
diff --git a/packages/core/package.json b/packages/core/package.json
index a9ab4ea1fb..601eff6e15 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -566,6 +566,11 @@
"types": "./dist/VStack/index.d.ts",
"default": "./dist/VStack/index.js"
},
+ "./VisuallyHidden": {
+ "source": "./src/VisuallyHidden/index.ts",
+ "types": "./dist/VisuallyHidden/index.d.ts",
+ "default": "./dist/VisuallyHidden/index.js"
+ },
"./hooks": {
"source": "./src/hooks/index.ts",
"types": "./dist/hooks/index.d.ts",
diff --git a/packages/core/src/VisuallyHidden/VisuallyHidden.doc.mjs b/packages/core/src/VisuallyHidden/VisuallyHidden.doc.mjs
new file mode 100644
index 0000000000..b4216a8781
--- /dev/null
+++ b/packages/core/src/VisuallyHidden/VisuallyHidden.doc.mjs
@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'VisuallyHidden',
+ displayName: 'VisuallyHidden',
+ category: 'Utility',
+ keywords: ["visually hidden","sr-only","screen reader","accessibility","a11y","aria-live","hidden label","assistive technology"],
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: 'Content exposed to assistive technology while hidden from sight.',
+ },
+ {
+ name: 'as',
+ type: 'ElementType',
+ description: 'HTML tag to render as. Use a block element for live regions.',
+ default: "'span'",
+ },
+ ],
+ usage: {
+ description: 'Renders content in the accessibility tree while hiding it visually. Use for accessible names on icon-only controls, aria-live announcement regions, and supplementary screen-reader context. Deliberately has no styling props — the whole point is to stay invisible.',
+ bestPractices: [
+ { guidance: true, description: 'Use to give icon-only buttons and controls an accessible name that screen readers announce.' },
+ { guidance: true, description: 'Render as a block element (as="div") with aria-live to announce dynamic updates like drag-and-drop or result counts.' },
+ { guidance: false, description: 'Use it to hide content from everyone — it stays in the accessibility tree; use conditional rendering or `hidden` to remove content entirely.' },
+ { guidance: false, description: 'Put interactive controls inside it — the content is not visible and cannot receive pointer input.' },
+ ],
+ },
+};
+
+/** @type {import('../docs-types').ComponentDoc} */
+export const docsZh = {
+ name: 'VisuallyHidden',
+ displayName: 'VisuallyHidden',
+ props: [
+ {
+ name: 'children',
+ type: 'ReactNode',
+ description: '对辅助技术公开但对视觉隐藏的内容。',
+ },
+ {
+ name: 'as',
+ type: 'ElementType',
+ description: '要渲染的 HTML 标签。实时区域请使用块级元素。',
+ default: "'span'",
+ },
+ ],
+ usage: {
+ description: 'Renders content in the accessibility tree while hiding it visually. Use for accessible names on icon-only controls, aria-live announcement regions, and supplementary screen-reader context.',
+ bestPractices: [
+ { guidance: true, description: 'Use to give icon-only buttons and controls an accessible name that screen readers announce.' },
+ { guidance: true, description: 'Render as a block element (as="div") with aria-live to announce dynamic updates like drag-and-drop or result counts.' },
+ { guidance: false, description: 'Use it to hide content from everyone — it stays in the accessibility tree; use conditional rendering or `hidden` to remove content entirely.' },
+ { guidance: false, description: 'Put interactive controls inside it — the content is not visible and cannot receive pointer input.' },
+ ],
+ },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+ description: 'renders content in the a11y tree while hiding it visually (sr-only)',
+ usage: {
+ description: 'Renders content in the accessibility tree while hiding it visually. Use for accessible names on icon-only controls, aria-live announcement regions, and supplementary screen-reader context.',
+ bestPractices: [
+ { guidance: true, description: 'Use to give icon-only buttons and controls an accessible name that screen readers announce.' },
+ { guidance: true, description: 'Render as a block element (as="div") with aria-live to announce dynamic updates like drag-and-drop or result counts.' },
+ { guidance: false, description: 'Use it to hide content from everyone — it stays in the accessibility tree; use conditional rendering or `hidden` to remove content entirely.' },
+ { guidance: false, description: 'Put interactive controls inside it — the content is not visible and cannot receive pointer input.' },
+ ],
+ },
+ propDescriptions: {
+ children: 'content exposed to AT while visually hidden',
+ as: 'HTML tag to render as; block element for live regions',
+ },
+};
diff --git a/packages/core/src/VisuallyHidden/VisuallyHidden.test.tsx b/packages/core/src/VisuallyHidden/VisuallyHidden.test.tsx
new file mode 100644
index 0000000000..da39fcbda3
--- /dev/null
+++ b/packages/core/src/VisuallyHidden/VisuallyHidden.test.tsx
@@ -0,0 +1,76 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file VisuallyHidden.test.tsx
+ * @input Uses vitest, @testing-library/react, VisuallyHidden component
+ * @output Unit tests for VisuallyHidden rendering + a11y behavior
+ * @position Testing; validates VisuallyHidden.tsx implementation
+ *
+ * SYNC: When VisuallyHidden.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {createRef} from 'react';
+import {VisuallyHidden} from './VisuallyHidden';
+
+describe('VisuallyHidden', () => {
+ it('renders its children in the accessibility tree', () => {
+ render(<VisuallyHidden>Delete incident</VisuallyHidden>);
+ // Present in the a11y tree (getByText finds it — it is not display:none).
+ expect(screen.getByText('Delete incident')).toBeInTheDocument();
+ });
+
+ it('renders a <span> by default', () => {
+ render(<VisuallyHidden>Label</VisuallyHidden>);
+ expect(screen.getByText('Label').tagName).toBe('SPAN');
+ });
+
+ it('renders a custom element via the `as` prop', () => {
+ render(
+ <VisuallyHidden as="div" aria-live="polite">
+ Moved task to Done
+ </VisuallyHidden>,
+ );
+ const el = screen.getByText('Moved task to Done');
+ expect(el.tagName).toBe('DIV');
+ expect(el).toHaveAttribute('aria-live', 'polite');
+ });
+
+ it('applies the clip styles that hide it visually', () => {
+ render(<VisuallyHidden>Hidden</VisuallyHidden>);
+ const el = screen.getByText('Hidden');
+ // jsdom does not apply the stylesheet, but the StyleX class is attached.
+ expect(el.getAttribute('class')).toBeTruthy();
+ // It must NOT be display:none / hidden — it stays in the a11y tree.
+ expect(el).not.toHaveAttribute('hidden');
+ });
+
+ it('forwards a ref to the rendered element', () => {
+ const ref = createRef<HTMLElement>();
+ render(<VisuallyHidden ref={ref}>Ref target</VisuallyHidden>);
+ expect(ref.current).toBeInstanceOf(HTMLElement);
+ expect(ref.current?.textContent).toBe('Ref target');
+ });
+
+ it('passes through arbitrary BaseProps (id, role, data-*)', () => {
+ render(
+ <VisuallyHidden id="announcer" role="status" data-testid="vh">
+ Status
+ </VisuallyHidden>,
+ );
+ const el = screen.getByTestId('vh');
+ expect(el).toHaveAttribute('id', 'announcer');
+ expect(el).toHaveAttribute('role', 'status');
+ });
+
+ it('gives an icon-only control an accessible name', () => {
+ render(
+ <button type="button">
+ <span aria-hidden="true">🗑️</span>
+ <VisuallyHidden>Delete</VisuallyHidden>
+ </button>,
+ );
+ expect(screen.getByRole('button', {name: 'Delete'})).toBeInTheDocument();
+ });
+});
diff --git a/packages/core/src/VisuallyHidden/VisuallyHidden.tsx b/packages/core/src/VisuallyHidden/VisuallyHidden.tsx
new file mode 100644
index 0000000000..94a6ec0213
--- /dev/null
+++ b/packages/core/src/VisuallyHidden/VisuallyHidden.tsx
@@ -0,0 +1,113 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file VisuallyHidden.tsx
+ * @input Uses React createElement/ElementType, stylex
+ * @output Exports VisuallyHidden component and VisuallyHiddenProps
+ * @position Accessibility primitive; renders content in the a11y tree while
+ * hiding it visually (icon-only labels, aria-live regions, SR-only context)
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/VisuallyHidden/VisuallyHidden.doc.mjs
+ * - /packages/core/src/VisuallyHidden/VisuallyHidden.test.tsx
+ * - /apps/storybook/stories/VisuallyHidden.stories.tsx
+ */
+
+import {createElement, type ElementType, type ReactNode, type Ref} from 'react';
+import type {BaseProps} from '../BaseProps';
+import * as stylex from '@stylexjs/stylex';
+
+/**
+ * VisuallyHidden is deliberately styling-free: it exists to *not* be seen, so it
+ * intentionally omits `xstyle`/`className`/`style`. The clip block is fixed and
+ * non-overridable — styling a visually-hidden node is always a mistake. The
+ * accessibility pass-throughs from `BaseProps` (`aria-*`, `role`, `id`,
+ * `data-*`, event handlers) remain, since the live-region use case needs them.
+ */
+export interface VisuallyHiddenProps extends Omit<
+ BaseProps<HTMLElement>,
+ 'className' | 'style'
+> {
+ /** Ref forwarded to the rendered element. */
+ ref?: React.Ref<HTMLElement>;
+
+ /** Content to expose to assistive technology while hidden from sight. */
+ children: ReactNode;
+
+ /**
+ * HTML tag to render as. Defaults to `'span'` (inline) for the common
+ * icon-label case; pass a block element such as `'div'` when wrapping block
+ * content or hosting an `aria-live` region. This is a structural choice, not
+ * a visual one.
+ *
+ * @default 'span'
+ */
+ as?: ElementType;
+}
+
+const styles = stylex.create({
+ // Canonical "visually hidden" clip block. Uses `clip: rect(...)` (not
+ // clip-path) for the widest assistive-tech/browser support. `inset` pins the
+ // 1px box to the top-left so a positioned ancestor cannot reveal it, and
+ // pointer/selection are disabled so the hidden node can't catch clicks or be
+ // text-selected.
+ visuallyHidden: {
+ position: 'absolute',
+ width: 1,
+ height: 1,
+ margin: -1,
+ padding: 0,
+ overflow: 'hidden',
+ clip: 'rect(0, 0, 0, 0)',
+ whiteSpace: 'nowrap',
+ borderStyle: 'none',
+ insetBlockStart: 0,
+ insetInlineStart: 0,
+ pointerEvents: 'none',
+ userSelect: 'none',
+ },
+});
+
+/**
+ * Renders its children in the accessibility tree while hiding them visually.
+ *
+ * Use for content that assistive technology must perceive but sighted users
+ * should not see: accessible names for icon-only controls, `aria-live`
+ * announcement regions, and supplementary screen-reader context.
+ *
+ * @example
+ * ```
+ * // Accessible name for an icon-only button
+ * <IconButton icon="trash" label="">
+ * <VisuallyHidden>Delete incident</VisuallyHidden>
+ * </IconButton>
+ *
+ * // Live region for announcements
+ * <VisuallyHidden as="div" aria-live="polite">
+ * {`Moved ${task} to ${column}`}
+ * </VisuallyHidden>
+ * ```
+ */
+export function VisuallyHidden({
+ children,
+ as: element = 'span',
+ ref,
+ ...props
+}: VisuallyHiddenProps) {
+ return createElement(
+ element,
+ {
+ ref: ref as Ref<Element>,
+ // Spread consumer props (aria-*, role, id, data-*, handlers) first, then
+ // the fixed clip styles, so the visually-hidden class can never be
+ // displaced. There is no consumer className/style to merge — by design.
+ ...props,
+ ...stylex.props(styles.visuallyHidden),
+ },
+ children,
+ );
+}
+
+VisuallyHidden.displayName = 'VisuallyHidden';
diff --git a/packages/core/src/VisuallyHidden/index.ts b/packages/core/src/VisuallyHidden/index.ts
new file mode 100644
index 0000000000..97a96fb266
--- /dev/null
+++ b/packages/core/src/VisuallyHidden/index.ts
@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports from VisuallyHidden.tsx
+ * @output Exports VisuallyHidden component and props type
+ * @position Package entry point for VisuallyHidden
+ *
+ * SYNC: When modified, update /packages/core/src/VisuallyHidden/VisuallyHidden.doc.mjs
+ */
+
+export {VisuallyHidden} from './VisuallyHidden';
+export type {VisuallyHiddenProps} from './VisuallyHidden';
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 4543881f4c..a6a01ca70b 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -42,6 +42,7 @@ export * from './Collapsible';
export * from './RadioList';
export * from './Resizable';
export * from './Divider';
+export * from './VisuallyHidden';
export * from './EmptyState';
export * from './Lightbox';
export * from './Link';