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.mdnew file mode 100644index 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).+@cixzhangdiff --git a/apps/storybook/stories/VisuallyHidden.stories.tsx b/apps/storybook/stories/VisuallyHidden.stories.tsxnew file mode 100644index 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.jsonindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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';