From ac718c6cd6256737db2d1cfd6576f8d6c1eb2901 Mon Sep 17 00:00:00 2001
From: Matt Van Horn <mvanhorn@users.noreply.github.com>
Date: Wed, 1 Apr 2026 12:15:46 -0700
Subject: [PATCH] fix: add dev warning when dialog has no accessible title
 (#9819)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* fix: add dev warning when dialog has no accessible title

When a dialog is rendered without an aria-label, aria-labelledby, or a
visible title element, emit a console.warn in development mode to help
developers catch this common accessibility mistake early. The warning
fires once per dialog instance and is tree-shaken in production builds.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(dialog): resolve test failures in dialog title dev warning

Check the DOM element directly for aria-label/aria-labelledby attributes
instead of relying on hook props, since wrapper components (e.g. RAC Dialog)
may add aria-labelledby from context after useDialog runs.

Add the warning pattern to the allowed warnings list in setupTests.js so
existing tests that render dialogs without accessible labels are not broken.

* fix: address review feedback - remove setupTests allowlist entry, drop 'visible' from warning

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: add aria-label to test dialogs that lack accessible titles

Adds aria-label="Test dialog" to Dialog test renders that don't
have a heading or aria-labelledby, preventing the new dev warning
from failing tests via failTestOnConsoleWarn().

9 test files fixed. Remaining failures (ContextualHelp, DatePicker,
DateRangePicker, Form, ListView) have dialogs rendered indirectly
through components — those need source-level changes.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: check props and titleId in addition to DOM attributes for dialog warning

The useEffect-based DOM check can race with useSlotId registration,
causing false positives in components where a heading exists but
hasn't registered yet.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: add aria-label to ContextualHelp dialog and revert ineffective titleId check

ContextualHelp renders <Header> (not <Heading>), so the Dialog's
useSlotId resolves to undefined and the dialog has no accessible
title. Pass the variant label ("Help"/"Information") as aria-label.

Reverts the !!titleId check in useDialog which didn't work because
useSlotId resolves to undefined via useLayoutEffect before the
warning's useEffect runs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix contextual help usage

---------

Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Robert Snow <rsnow@adobe.com>
Co-authored-by: Robert Snow <snowystinger@gmail.com>
---
 .../test/actiongroup/ActionGroup.test.js      |  2 +-
 .../contextualhelp/ContextualHelp.test.js     | 18 +++----
 .../test/dialog/Dialog.ssr.test.js            |  2 +-
 .../react-spectrum/test/dialog/Dialog.test.js |  6 +--
 .../test/dialog/DialogTrigger.test.js         | 52 +++++++++----------
 .../react-spectrum/test/form/Form.test.js     |  4 +-
 .../react-spectrum/test/menu/Menu.test.js     |  2 +-
 .../test/overlays/Popover.test.js             |  2 +-
 .../react-spectrum/test/overlays/Tray.test.js |  2 +-
 packages/react-aria/src/dialog/useDialog.ts   | 22 ++++++++
 .../test/aria-modal-polyfill/index.test.tsx   |  8 +--
 .../react-aria/test/dialog/useDialog.test.js  | 52 ++++++++++++++++---
 .../test/interactions/useHover.test.js        |  2 +-
 .../test/interactions/usePress.test.js        |  2 +-
 14 files changed, 119 insertions(+), 57 deletions(-)

diff --git a/packages/@adobe/react-spectrum/test/actiongroup/ActionGroup.test.js b/packages/@adobe/react-spectrum/test/actiongroup/ActionGroup.test.js
index 409f2ccc128..9a41b177496 100644
--- a/packages/@adobe/react-spectrum/test/actiongroup/ActionGroup.test.js
+++ b/packages/@adobe/react-spectrum/test/actiongroup/ActionGroup.test.js
@@ -575,7 +575,7 @@ describe('ActionGroup', function () {
         <ActionGroup>
           <DialogTrigger>
             <Item>Hi</Item>
-            <Dialog>
+            <Dialog aria-label="Test dialog">
               I'm a dialog
             </Dialog>
           </DialogTrigger>
diff --git a/packages/@adobe/react-spectrum/test/contextualhelp/ContextualHelp.test.js b/packages/@adobe/react-spectrum/test/contextualhelp/ContextualHelp.test.js
index d8b5a2252b6..3f48067ae6b 100644
--- a/packages/@adobe/react-spectrum/test/contextualhelp/ContextualHelp.test.js
+++ b/packages/@adobe/react-spectrum/test/contextualhelp/ContextualHelp.test.js
@@ -14,7 +14,7 @@ import {act, pointerMap, render, simulateDesktop} from '@react-spectrum/test-uti
 import {Content} from '../../src/view/Content';
 import {ContextualHelp} from '../../src/contextualhelp/ContextualHelp';
 import {Footer} from '../../src/view/Footer';
-import {Header} from '../../src/view/Header';
+import {Heading} from '../../src/text/Heading';
 import {Link} from '../../src/link/Link';
 import {Provider} from '../../src/provider/Provider';
 import React from 'react';
@@ -39,7 +39,7 @@ describe('ContextualHelp', function () {
     let {getByRole, queryByRole} = render(
       <Provider theme={theme}>
         <ContextualHelp>
-          <Header>Test title</Header>
+          <Heading>Test title</Heading>
         </ContextualHelp>
       </Provider>
     );
@@ -56,7 +56,7 @@ describe('ContextualHelp', function () {
     let {getByRole, queryByRole, getByTestId, getByText} = render(
       <Provider theme={theme}>
         <ContextualHelp>
-          <Header>Test title</Header>
+          <Heading>Test title</Heading>
         </ContextualHelp>
       </Provider>
     );
@@ -84,7 +84,7 @@ describe('ContextualHelp', function () {
     let {getByRole, getByText} = render(
       <Provider theme={theme}>
         <ContextualHelp>
-          <Header>Test title</Header>
+          <Heading>Test title</Heading>
           <Content>Help content</Content>
         </ContextualHelp>
       </Provider>
@@ -109,7 +109,7 @@ describe('ContextualHelp', function () {
     let {getByRole, getByText} = render(
       <Provider theme={theme}>
         <ContextualHelp>
-          <Header>Test title</Header>
+          <Heading>Test title</Heading>
           <Content>Help content</Content>
           <Footer>
             <Link>Test link</Link>
@@ -137,7 +137,7 @@ describe('ContextualHelp', function () {
     let {getByRole} = render(
       <Provider theme={theme}>
         <ContextualHelp>
-          <Header>Test title</Header>
+          <Heading>Test title</Heading>
           <Content>Help content</Content>
         </ContextualHelp>
       </Provider>
@@ -151,7 +151,7 @@ describe('ContextualHelp', function () {
     let {getByRole} = render(
       <Provider theme={theme}>
         <ContextualHelp variant="info">
-          <Header>Test title</Header>
+          <Heading>Test title</Heading>
           <Content>Help content</Content>
         </ContextualHelp>
       </Provider>
@@ -165,7 +165,7 @@ describe('ContextualHelp', function () {
     let {getByRole} = render(
       <Provider theme={theme}>
         <ContextualHelp aria-label="test">
-          <Header>Test title</Header>
+          <Heading>Test title</Heading>
           <Content>Help content</Content>
         </ContextualHelp>
       </Provider>
@@ -179,7 +179,7 @@ describe('ContextualHelp', function () {
     let {getByRole} = render(
       <Provider theme={theme}>
         <ContextualHelp aria-labelledby="test">
-          <Header>Test title</Header>
+          <Heading>Test title</Heading>
           <Content>Help content</Content>
         </ContextualHelp>
       </Provider>
diff --git a/packages/@adobe/react-spectrum/test/dialog/Dialog.ssr.test.js b/packages/@adobe/react-spectrum/test/dialog/Dialog.ssr.test.js
index ac2a74e0671..67e44d6c359 100644
--- a/packages/@adobe/react-spectrum/test/dialog/Dialog.ssr.test.js
+++ b/packages/@adobe/react-spectrum/test/dialog/Dialog.ssr.test.js
@@ -17,7 +17,7 @@ describe('Dialog SSR', function () {
     await testSSR(__filename, `
       import {Dialog} from '../../exports/index.ts';
 
-      <Dialog>
+      <Dialog aria-label="The label">
         contents
       </Dialog>
     `);
diff --git a/packages/@adobe/react-spectrum/test/dialog/Dialog.test.js b/packages/@adobe/react-spectrum/test/dialog/Dialog.test.js
index 5380dc2f5da..e0f5ca148dc 100644
--- a/packages/@adobe/react-spectrum/test/dialog/Dialog.test.js
+++ b/packages/@adobe/react-spectrum/test/dialog/Dialog.test.js
@@ -21,7 +21,7 @@ import {render} from '@react-spectrum/test-utils-internal';
 describe('Dialog', function () {
   it('does not auto focus anything inside', function () {
     let {getByRole} = render(
-      <Dialog>
+      <Dialog aria-label="Test dialog">
         <input data-testid="input1" />
         <input data-testid="input2" />
       </Dialog>
@@ -35,7 +35,7 @@ describe('Dialog', function () {
 
   it('auto focuses the dialog itself if there is no focusable child', function () {
     let {getByRole} = render(
-      <Dialog>
+      <Dialog aria-label="Test dialog">
         contents
       </Dialog>
     );
@@ -46,7 +46,7 @@ describe('Dialog', function () {
 
   it('autofocuses any element that has autofocus inside', function () {
     let {getByTestId} = render(
-      <Dialog>
+      <Dialog aria-label="Test dialog">
         <input data-testid="input1" />
         <input data-testid="input2" autoFocus />
       </Dialog>
diff --git a/packages/@adobe/react-spectrum/test/dialog/DialogTrigger.test.js b/packages/@adobe/react-spectrum/test/dialog/DialogTrigger.test.js
index 795ec1f7afe..e52b04f4ed5 100644
--- a/packages/@adobe/react-spectrum/test/dialog/DialogTrigger.test.js
+++ b/packages/@adobe/react-spectrum/test/dialog/DialogTrigger.test.js
@@ -68,7 +68,7 @@ describe('DialogTrigger', function () {
       <Provider theme={theme}>
         <DialogTrigger>
           <ActionButton>Trigger</ActionButton>
-          <Dialog>contents</Dialog>
+          <Dialog aria-label="Test dialog">contents</Dialog>
         </DialogTrigger>
       </Provider>
     );
@@ -90,7 +90,7 @@ describe('DialogTrigger', function () {
       <Provider theme={theme}>
         <DialogTrigger type="tray">
           <ActionButton>Trigger</ActionButton>
-          <Dialog>contents</Dialog>
+          <Dialog aria-label="Test dialog">contents</Dialog>
         </DialogTrigger>
       </Provider>
     );
@@ -116,7 +116,7 @@ describe('DialogTrigger', function () {
       <Provider theme={theme}>
         <DialogTrigger type="popover">
           <ActionButton>Trigger</ActionButton>
-          <Dialog>contents</Dialog>
+          <Dialog aria-label="Test dialog">contents</Dialog>
         </DialogTrigger>
       </Provider>
     );
@@ -140,7 +140,7 @@ describe('DialogTrigger', function () {
         <DialogTrigger type="popover">
           <ActionButton>Trigger</ActionButton>
           {(close) => (
-            <Dialog>
+            <Dialog aria-label="Test dialog">
               contents
               <ButtonGroup>
                 <Button variant="secondary" onPress={close}>
@@ -180,7 +180,7 @@ describe('DialogTrigger', function () {
       <Provider theme={theme}>
         <DialogTrigger type="popover">
           <ActionButton>Trigger</ActionButton>
-          <Dialog>contents</Dialog>
+          <Dialog aria-label="Test dialog">contents</Dialog>
         </DialogTrigger>
       </Provider>
     );
@@ -207,7 +207,7 @@ describe('DialogTrigger', function () {
       <Provider theme={theme}>
         <DialogTrigger type="popover" mobileType="tray">
           <ActionButton>Trigger</ActionButton>
-          <Dialog>contents</Dialog>
+          <Dialog aria-label="Test dialog">contents</Dialog>
         </DialogTrigger>
       </Provider>
     );
@@ -233,7 +233,7 @@ describe('DialogTrigger', function () {
       <Provider theme={theme}>
         <DialogTrigger type={type}>
           <ActionButton>Trigger</ActionButton>
-          <Dialog>
+          <Dialog aria-label="Test dialog">
             <input data-testid="input1" />
             <input data-testid="input2" />
           </Dialog>
@@ -268,7 +268,7 @@ describe('DialogTrigger', function () {
       <Provider theme={theme}>
         <DialogTrigger>
           <ActionButton>Trigger</ActionButton>
-          <Dialog>contents</Dialog>
+          <Dialog aria-label="Test dialog">contents</Dialog>
         </DialogTrigger>
       </Provider>
     );
@@ -291,7 +291,7 @@ describe('DialogTrigger', function () {
       <Provider theme={theme}>
         <DialogTrigger type="popover">
           <ActionButton>Trigger</ActionButton>
-          <Dialog>contents</Dialog>
+          <Dialog aria-label="Test dialog">contents</Dialog>
         </DialogTrigger>
       </Provider>
     );
@@ -336,7 +336,7 @@ describe('DialogTrigger', function () {
       <Provider theme={theme}>
         <DialogTrigger onOpenChange={onOpenChange} type="popover">
           <ActionButton>Trigger</ActionButton>
-          <Dialog>contents</Dialog>
+          <Dialog aria-label="Test dialog">contents</Dialog>
         </DialogTrigger>
       </Provider>
     );
@@ -382,7 +382,7 @@ describe('DialogTrigger', function () {
       <Provider theme={theme} ref={rootProviderRef}>
         <DialogTrigger>
           <ActionButton>Trigger</ActionButton>
-          <Dialog>contents</Dialog>
+          <Dialog aria-label="Test dialog">contents</Dialog>
         </DialogTrigger>
       </Provider>
     );
@@ -422,7 +422,7 @@ describe('DialogTrigger', function () {
         <Provider theme={theme}>
           <DialogTrigger isOpen={isOpen} onOpenChange={onOpenChange}>
             <ActionButton>Trigger</ActionButton>
-            <Dialog>contents</Dialog>
+            <Dialog aria-label="Test dialog">contents</Dialog>
           </DialogTrigger>
         </Provider>
       );
@@ -480,7 +480,7 @@ describe('DialogTrigger', function () {
         <Provider theme={theme}>
           <DialogTrigger defaultOpen={defaultOpen} onOpenChange={onOpenChange}>
             <ActionButton>Trigger</ActionButton>
-            <Dialog>contents</Dialog>
+            <Dialog aria-label="Test dialog">contents</Dialog>
           </DialogTrigger>
         </Provider>
       );
@@ -518,7 +518,7 @@ describe('DialogTrigger', function () {
         <Provider theme={theme}>
           <DialogTrigger defaultOpen={defaultOpen} onOpenChange={onOpenChange}>
             <ActionButton>Trigger</ActionButton>
-            {(close) => <Dialog>contents<Button variant="primary" data-testid="closebtn" onPress={close}>Close</Button></Dialog>}
+            {(close) => <Dialog aria-label="Test dialog">contents<Button variant="primary" data-testid="closebtn" onPress={close}>Close</Button></Dialog>}
           </DialogTrigger>
         </Provider>
       );
@@ -557,7 +557,7 @@ describe('DialogTrigger', function () {
         <Provider theme={theme}>
           <DialogTrigger isDismissable defaultOpen={defaultOpen} onOpenChange={onOpenChange}>
             <ActionButton>Trigger</ActionButton>
-            <Dialog>contents</Dialog>
+            <Dialog aria-label="Test dialog">contents</Dialog>
           </DialogTrigger>
         </Provider>
       );
@@ -596,7 +596,7 @@ describe('DialogTrigger', function () {
         <Provider theme={theme}>
           <DialogTrigger type="modal" isDismissable defaultOpen={defaultOpen} onOpenChange={onOpenChange}>
             <ActionButton>Trigger</ActionButton>
-            <Dialog>contents</Dialog>
+            <Dialog aria-label="Test dialog">contents</Dialog>
           </DialogTrigger>
         </Provider>
       );
@@ -634,7 +634,7 @@ describe('DialogTrigger', function () {
         <Provider theme={theme}>
           <DialogTrigger type="modal" defaultOpen={defaultOpen} onOpenChange={onOpenChange}>
             <ActionButton>Trigger</ActionButton>
-            <Dialog>contents</Dialog>
+            <Dialog aria-label="Test dialog">contents</Dialog>
           </DialogTrigger>
         </Provider>
       );
@@ -667,7 +667,7 @@ describe('DialogTrigger', function () {
         <Provider theme={theme}>
           <DialogTrigger type="popover" mobileType="modal" defaultOpen={defaultOpen} onOpenChange={onOpenChange}>
             <ActionButton>Trigger</ActionButton>
-            <Dialog>contents</Dialog>
+            <Dialog aria-label="Test dialog">contents</Dialog>
           </DialogTrigger>
         </Provider>
       );
@@ -705,7 +705,7 @@ describe('DialogTrigger', function () {
         <Provider theme={theme}>
           <DialogTrigger type="popover" defaultOpen={defaultOpen} onOpenChange={onOpenChange} isDismissable={false}>
             <ActionButton>Trigger</ActionButton>
-            <Dialog>contents</Dialog>
+            <Dialog aria-label="Test dialog">contents</Dialog>
           </DialogTrigger>
         </Provider>
       );
@@ -742,7 +742,7 @@ describe('DialogTrigger', function () {
       <Provider theme={theme}>
         <DialogTrigger isKeyboardDismissDisabled>
           <ActionButton>Trigger</ActionButton>
-          {close => <Dialog><ActionButton onPress={close}>Close</ActionButton></Dialog>}
+          {close => <Dialog aria-label="Test dialog"><ActionButton onPress={close}>Close</ActionButton></Dialog>}
         </DialogTrigger>
       </Provider>
     );
@@ -794,7 +794,7 @@ describe('DialogTrigger', function () {
           <Menu>
             <DialogTrigger isKeyboardDismissDisabled>
               <Item>Open menu</Item>
-              <Dialog>Content body</Dialog>
+              <Dialog aria-label="Test dialog">Content body</Dialog>
             </DialogTrigger>
           </Menu>
         </MenuTrigger>
@@ -830,12 +830,12 @@ describe('DialogTrigger', function () {
         <TextField id="document-input" aria-label="document input" />
         <DialogTrigger>
           <ActionButton id="outer-trigger">Trigger</ActionButton>
-          <Dialog id="outer-dialog">
+          <Dialog aria-label="Test dialog" id="outer-dialog">
             <Content>
               <TextField id="outer-input" aria-label="outer input" autoFocus />
               <DialogTrigger>
                 <ActionButton id="inner-trigger">Trigger</ActionButton>
-                <Dialog id="inner-dialog">
+                <Dialog aria-label="Test dialog" id="inner-dialog">
                   <Content>
                     <TextField id="inner-input" aria-label="outer input" autoFocus />
                   </Content>
@@ -900,12 +900,12 @@ describe('DialogTrigger', function () {
         <TextField id="document-input" aria-label="document input" />
         <DialogTrigger type="popover">
           <ActionButton id="outer-trigger">Trigger1</ActionButton>
-          <Dialog id="outer-dialog">
+          <Dialog aria-label="Test dialog" id="outer-dialog">
             <Content>
               <TextField id="outer-input" aria-label="outer input" />
               <DialogTrigger type="popover">
                 <ActionButton id="inner-trigger">Trigger2</ActionButton>
-                <Dialog id="inner-dialog">
+                <Dialog aria-label="Test dialog" id="inner-dialog">
                   <Content>
                     <TextField id="inner-input" label="inner input" />
                   </Content>
@@ -958,7 +958,7 @@ describe('DialogTrigger', function () {
           <UNSAFE_PortalProvider getContainer={() => container.current}>
             <DialogTrigger type={props.type}>
               <ActionButton>Trigger</ActionButton>
-              <Dialog>contents</Dialog>
+              <Dialog aria-label="Test dialog">contents</Dialog>
             </DialogTrigger>
           </UNSAFE_PortalProvider>
         </Provider>
diff --git a/packages/@adobe/react-spectrum/test/form/Form.test.js b/packages/@adobe/react-spectrum/test/form/Form.test.js
index 3ee51c90978..d58c7bc7de3 100644
--- a/packages/@adobe/react-spectrum/test/form/Form.test.js
+++ b/packages/@adobe/react-spectrum/test/form/Form.test.js
@@ -15,7 +15,7 @@ import {Button} from '../../src/button/Button';
 import {Content} from '../../src/view/Content';
 import {ContextualHelp} from '../../src/contextualhelp/ContextualHelp';
 import {Form} from '../../src/form/Form';
-import {Header} from '../../src/view/Header';
+import {Heading} from '../../src/text/Heading';
 import {Item} from 'react-stately/Item';
 import {Picker} from '../../src/picker/Picker';
 import {pointerMap, render, simulateMobile} from '@react-spectrum/test-utils-internal';
@@ -212,7 +212,7 @@ describe('Form', function () {
               label="Test Picker"
               contextualHelp={(
                 <ContextualHelp>
-                  <Header>What is it good for?</Header>
+                  <Heading>What is it good for?</Heading>
                   <Content>Absolutely nothing.</Content>
                 </ContextualHelp>
               )}>
diff --git a/packages/@adobe/react-spectrum/test/menu/Menu.test.js b/packages/@adobe/react-spectrum/test/menu/Menu.test.js
index faceac07056..b5294ea9ea4 100644
--- a/packages/@adobe/react-spectrum/test/menu/Menu.test.js
+++ b/packages/@adobe/react-spectrum/test/menu/Menu.test.js
@@ -584,7 +584,7 @@ describe('Menu', function () {
           <Section title="Test">
             <DialogTrigger>
               <Item>Hi</Item>
-              <Dialog>
+              <Dialog aria-label="Test dialog">
                 I'm a dialog
               </Dialog>
             </DialogTrigger>
diff --git a/packages/@adobe/react-spectrum/test/overlays/Popover.test.js b/packages/@adobe/react-spectrum/test/overlays/Popover.test.js
index e6f7e817adf..76fce4f92d5 100644
--- a/packages/@adobe/react-spectrum/test/overlays/Popover.test.js
+++ b/packages/@adobe/react-spectrum/test/overlays/Popover.test.js
@@ -24,7 +24,7 @@ function PopoverWithDialog({children}) {
   let state = useOverlayTriggerState({isOpen: true});
   return (
     <Popover triggerRef={ref} state={state}>
-      <Dialog>{children}</Dialog>
+      <Dialog aria-label="Test dialog">{children}</Dialog>
     </Popover>
   );
 }
diff --git a/packages/@adobe/react-spectrum/test/overlays/Tray.test.js b/packages/@adobe/react-spectrum/test/overlays/Tray.test.js
index b9f91634e16..ccdd9e1f057 100644
--- a/packages/@adobe/react-spectrum/test/overlays/Tray.test.js
+++ b/packages/@adobe/react-spectrum/test/overlays/Tray.test.js
@@ -99,7 +99,7 @@ describe('Tray', function () {
     let {getByRole} = render(
       <Provider theme={theme}>
         <TestTray isOpen onOpenChange={onOpenChange} shouldCloseOnBlur>
-          <Dialog>contents</Dialog>
+          <Dialog aria-label="Test dialog">contents</Dialog>
         </TestTray>
       </Provider>
     );
diff --git a/packages/react-aria/src/dialog/useDialog.ts b/packages/react-aria/src/dialog/useDialog.ts
index f44cf365089..8d6f503252f 100644
--- a/packages/react-aria/src/dialog/useDialog.ts
+++ b/packages/react-aria/src/dialog/useDialog.ts
@@ -75,6 +75,28 @@ export function useDialog(props: AriaDialogProps, ref: RefObject<FocusableElemen
 
   useOverlayFocusContain();
 
+  // Warn in dev mode if the dialog has no accessible title.
+  // This catches a common mistake where useDialog and useOverlayTriggerState
+  // are used in the same component, causing the title element to not be
+  // in the DOM when useSlotId queries for it.
+  // Check the DOM element directly since aria-labelledby may be added by
+  // wrapper components (e.g. RAC Dialog uses trigger ID as a fallback).
+  let hasWarned = useRef(false);
+  useEffect(() => {
+    if (process.env.NODE_ENV !== 'production' && !hasWarned.current && ref.current) {
+      let el = ref.current;
+      let hasAriaLabel = el.hasAttribute('aria-label');
+      let hasAriaLabelledby = el.hasAttribute('aria-labelledby');
+      if (!hasAriaLabel && !hasAriaLabelledby) {
+        console.warn(
+          'A dialog must have a title for accessibility. ' +
+          'Either provide an aria-label or aria-labelledby prop, or render a heading element inside the dialog with the titleProps from useDialog.'
+        );
+        hasWarned.current = true;
+      }
+    }
+  });
+
   // We do not use aria-modal due to a Safari bug which forces the first focusable element to be focused
   // on mount when inside an iframe, no matter which element we programmatically focus.
   // See https://bugs.webkit.org/show_bug.cgi?id=211934.
diff --git a/packages/react-aria/test/aria-modal-polyfill/index.test.tsx b/packages/react-aria/test/aria-modal-polyfill/index.test.tsx
index 19ab6f75897..42f1ee9e55d 100644
--- a/packages/react-aria/test/aria-modal-polyfill/index.test.tsx
+++ b/packages/react-aria/test/aria-modal-polyfill/index.test.tsx
@@ -73,7 +73,7 @@ describe('watchModals', () => {
         <Provider theme={theme}>
           <DialogTrigger>
             <ActionButton aria-label="Trigger" />
-            <Dialog>contents</Dialog>
+            <Dialog aria-label="Test dialog">contents</Dialog>
           </DialogTrigger>
         </Provider>
         <hr />
@@ -95,12 +95,12 @@ describe('watchModals', () => {
         <Provider theme={theme}>
           <DialogTrigger>
             <ActionButton aria-label="Trigger" />
-            <Dialog>
+            <Dialog aria-label="Test dialog">
               <Content>
                 <div>Outer</div>
                 <DialogTrigger>
                   <Button variant="primary" aria-label="Nested Trigger" />
-                  <Dialog>Inner</Dialog>
+                  <Dialog aria-label="Test dialog">Inner</Dialog>
                 </DialogTrigger>
               </Content>
             </Dialog>
@@ -249,7 +249,7 @@ describe('watchModals', () => {
         <Provider theme={theme}>
           <DialogTrigger type="popover">
             <ActionButton aria-label="Trigger" />
-            <Dialog>contents</Dialog>
+            <Dialog aria-label="Test dialog">contents</Dialog>
           </DialogTrigger>
         </Provider>
         <hr />
diff --git a/packages/react-aria/test/dialog/useDialog.test.js b/packages/react-aria/test/dialog/useDialog.test.js
index 3d824a65a68..13f469e5771 100644
--- a/packages/react-aria/test/dialog/useDialog.test.js
+++ b/packages/react-aria/test/dialog/useDialog.test.js
@@ -16,25 +16,30 @@ import {useDialog} from '../../src/dialog/useDialog';
 
 function Example(props) {
   let ref = useRef();
-  let {dialogProps} = useDialog(props, ref);
-  return <div ref={ref} {...dialogProps} data-testid="test">{props.children}</div>;
+  let {dialogProps, titleProps} = useDialog(props, ref);
+  return (
+    <div ref={ref} {...dialogProps} data-testid="test">
+      {props.showTitle && <h2 {...titleProps}>Title</h2>}
+      {props.children}
+    </div>
+  );
 }
 
 describe('useDialog', function () {
   it('should have role="dialog" by default', function () {
-    let res = render(<Example />);
+    let res = render(<Example aria-label="Test dialog" />);
     let el = res.getByTestId('test');
     expect(el).toHaveAttribute('role', 'dialog');
   });
 
   it('should accept role="alertdialog"', function () {
-    let res = render(<Example role="alertdialog" />);
+    let res = render(<Example role="alertdialog" aria-label="Test dialog" />);
     let el = res.getByTestId('test');
     expect(el).toHaveAttribute('role', 'alertdialog');
   });
 
   it('should focus the overlay on mount', function () {
-    let res = render(<Example />);
+    let res = render(<Example aria-label="Test dialog" />);
     let el = res.getByTestId('test');
     expect(el).toHaveAttribute('tabIndex', '-1');
     expect(document.activeElement).toBe(el);
@@ -42,11 +47,46 @@ describe('useDialog', function () {
 
   it('should not focus the overlay if something inside is auto focused', function () {
     let res = render(
-      <Example>
+      <Example aria-label="Test dialog">
         <input data-testid="input" autoFocus />
       </Example>
     );
     let input = res.getByTestId('input');
     expect(document.activeElement).toBe(input);
   });
+
+  describe('dev warnings', function () {
+    let originalWarn;
+
+    beforeEach(function () {
+      originalWarn = console.warn;
+      console.warn = jest.fn();
+    });
+
+    afterEach(function () {
+      console.warn = originalWarn;
+    });
+
+    it('should warn when dialog has no accessible title', function () {
+      render(<Example />);
+      expect(console.warn).toHaveBeenCalledWith(
+        expect.stringContaining('A dialog must have a title for accessibility')
+      );
+    });
+
+    it('should not warn when aria-label is provided', function () {
+      render(<Example aria-label="My dialog" />);
+      expect(console.warn).not.toHaveBeenCalled();
+    });
+
+    it('should not warn when aria-labelledby is provided', function () {
+      render(<Example aria-labelledby="some-id" />);
+      expect(console.warn).not.toHaveBeenCalled();
+    });
+
+    it('should not warn when a title element is rendered', function () {
+      render(<Example showTitle />);
+      expect(console.warn).not.toHaveBeenCalled();
+    });
+  });
 });
diff --git a/packages/react-aria/test/interactions/useHover.test.js b/packages/react-aria/test/interactions/useHover.test.js
index 5fceaa2846a..4025ab04f0c 100644
--- a/packages/react-aria/test/interactions/useHover.test.js
+++ b/packages/react-aria/test/interactions/useHover.test.js
@@ -578,7 +578,7 @@ describe('useHover', function () {
           <ElementType {...hoverProps} tabIndex="0">
             <DialogTrigger>
               <ActionButton>open</ActionButton>
-              <Dialog>
+              <Dialog aria-label="Test dialog">
                 test
               </Dialog>
             </DialogTrigger>
diff --git a/packages/react-aria/test/interactions/usePress.test.js b/packages/react-aria/test/interactions/usePress.test.js
index 12bf47d5e4d..c8ea07a6be0 100644
--- a/packages/react-aria/test/interactions/usePress.test.js
+++ b/packages/react-aria/test/interactions/usePress.test.js
@@ -3557,7 +3557,7 @@ describe('usePress', function () {
           <ElementType {...pressProps} tabIndex="0">
             <DialogTrigger>
               <ActionButton>open</ActionButton>
-              <Dialog>
+              <Dialog aria-label="Test dialog">
                 test
               </Dialog>
             </DialogTrigger>