diff --git a/.changeset/loud-coins-shake.md b/.changeset/loud-coins-shake.md
new file mode 100644
index 0000000000..9843d0c0d8
--- /dev/null
+++ b/.changeset/loud-coins-shake.md
@@ -0,0 +1,21 @@
+---
+"@rhds/elements": minor
+---
+
+`<rh-dialog>`: Dialog now uses the native HTML `<dialog>` element internally.
+
+Note: the `overlay` CSS shadow part is now deprecated in favor of the `--rh-dialog-backdrop-background-color` CSS custom property.  It will still work, but you can expect the `overlay` part to be removed in a future version
+
+Before:
+
+```css
+rh-dialog::part(overlay) { ... }
+```
+
+After:
+
+```css
+rh-dialog {
+  --rh-dialog-backdrop-background-color: ghostwhite;
+}
+```
diff --git a/elements/rh-dialog/demo/color-context.html b/elements/rh-dialog/demo/color-context.html
index 90af9cf496..3ae29689c3 100644
--- a/elements/rh-dialog/demo/color-context.html
+++ b/elements/rh-dialog/demo/color-context.html
@@ -16,9 +16,7 @@ <h2 slot="header">Color Context</h2>
     <p>Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit. Donec sed
       odio dui. Maecenas faucibus mollis interdum. Fusce dapibus, tellus ac cursus commodo, tortor mauris
       condimentum nibh, ut fermentum massa justo sit amet risus.</p>
-    <rh-cta slot="footer">
-      <a href="#bar">Learn more</a>
-    </rh-cta>
+    <rh-cta slot="footer" href="#bar">Call to Action</rh-cta>
   </rh-dialog>
   <rh-button id="context-trigger">Open Dialog</rh-button>
 </rh-context-demo>
diff --git a/elements/rh-dialog/demo/events.html b/elements/rh-dialog/demo/events.html
index f3e55d7310..2eb0eeb718 100644
--- a/elements/rh-dialog/demo/events.html
+++ b/elements/rh-dialog/demo/events.html
@@ -6,9 +6,7 @@ <h2 slot="header">Modal dialog with a header</h2>
       aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
       fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit
       anim id est laborum.</p>
-    <rh-cta>
-      <a href="#bar">Learn more</a>
-    </rh-cta>
+    <rh-cta slot="footer" href="#bar">Call to Action</rh-cta>
   </rh-dialog>
   <rh-button id="trigger">Open</rh-button>
   <fieldset>
diff --git a/elements/rh-dialog/demo/lots-of-content.html b/elements/rh-dialog/demo/lots-of-content.html
index 195cb5df64..3088f0f683 100644
--- a/elements/rh-dialog/demo/lots-of-content.html
+++ b/elements/rh-dialog/demo/lots-of-content.html
@@ -57,9 +57,7 @@ <h2 slot="header">Modal with a header with a truly excessive super duper long ti
   <p>Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit. Donec sed
     odio dui. Maecenas faucibus mollis interdum. Fusce dapibus, tellus ac cursus commodo, tortor mauris
     condimentum nibh, ut fermentum massa justo sit amet risus.</p>
-  <rh-cta slot="footer">
-    <a href="#bar">Learn more</a>
-  </rh-cta>
+  <rh-cta slot="footer" href="#bar">Call to Action</rh-cta>
 </rh-dialog>
 
 <script type="module">
diff --git a/elements/rh-dialog/demo/no-header-content.html b/elements/rh-dialog/demo/no-header-content.html
index 120bf766ff..e8ca7e0465 100644
--- a/elements/rh-dialog/demo/no-header-content.html
+++ b/elements/rh-dialog/demo/no-header-content.html
@@ -1,15 +1,13 @@
 <rh-button id="no-header-content-trigger">Open</rh-button>
 <rh-dialog trigger="no-header-content-trigger">
-  <p>A modal with no slotted header content</p>
-  <h3>This has no header content</h3>
+  <h2>This dialog has no slotted header content</h2>
+  <p>All this content exists in the default slot.</p>
   <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore
     magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
     consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
     pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est
     laborum.</p>
-  <rh-cta id="test-dark-child">
-    <a href="#">Call-to-action</a>
-  </rh-cta>
+  <rh-cta slot="footer" href="#bar">Call to Action</rh-cta>
 </rh-dialog>
 
 <script type="module">
diff --git a/elements/rh-dialog/demo/no-headings.html b/elements/rh-dialog/demo/no-headings.html
index 28b666d63d..2680ff85a5 100644
--- a/elements/rh-dialog/demo/no-headings.html
+++ b/elements/rh-dialog/demo/no-headings.html
@@ -1,13 +1,12 @@
 <rh-button id="no-headings-trigger">Open</rh-button>
-<rh-dialog trigger="no-headings-trigger">
-  <p>This modal doesn't have any headings. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
-    tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
-    laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
-    cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui
-    officia deserunt mollit anim id est laborum.</p>
-  <rh-cta>
-    <a href="#">Call-to-action</a>
-  </rh-cta>
+<rh-dialog accessible-label="This dialog's accessible name" trigger="no-headings-trigger">
+  <p>This dialog uses the <code>accessible-label</code> attribute to define its accessible name for assistive technology.
+     If the dialog includes a heading, the heading automatically becomes its accessible name—as long as the
+     <code>accessible-label</code> attribute does not exist. If neither a heading nor the <code>accessible-label</code>
+     attribute are provided, the dialog's accessible name defaults to the text content of its trigger element.
+     Learn more about these attributes in the <a href="https://ux.redhat.com/elements/dialog/code/">rh-dialog docs</a>.
+  </p>
+  <rh-cta slot="footer" href="#">Call to Action</rh-cta>
 </rh-dialog>
 
 <script type="module">
diff --git a/elements/rh-dialog/demo/rh-dialog.html b/elements/rh-dialog/demo/rh-dialog.html
index 54dc315a9d..70f87cbf1f 100644
--- a/elements/rh-dialog/demo/rh-dialog.html
+++ b/elements/rh-dialog/demo/rh-dialog.html
@@ -6,9 +6,7 @@ <h2 slot="header">Modal dialog with a header</h2>
     aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
     fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit
     anim id est laborum.</p>
-  <rh-cta>
-    <a href="#bar">Learn more</a>
-  </rh-cta>
+  <rh-cta slot="footer" href="#bar">Call to Action</rh-cta>
 </rh-dialog>
 
 <script type="module">
diff --git a/elements/rh-dialog/docs/40-accessibility.md b/elements/rh-dialog/docs/40-accessibility.md
index 5b023d234e..a25975c541 100644
--- a/elements/rh-dialog/docs/40-accessibility.md
+++ b/elements/rh-dialog/docs/40-accessibility.md
@@ -37,17 +37,22 @@ A dialog can be opened by pressing `Enter` when the dialog trigger has focus. Wh
 
 ## Focus order
 
+When a dialog opens, the close dialog button receives focus by default. Users have the ability to tab through each focusable element in the dialog. Depending on the browser, reaching the last focusable element may either:
+
+  1. Loop focus back to the close button
+  1. Move to focusable elements within the browser’s chrome
+
+While the dialog is open, interactive elements on the underlying page cannot be focused.
+
+### Changing focus order depending on content
+
 When a dialog opens, the element that should receive focus depends on the content and size of the modal. To help you decide where to place focus, follow these guidelines:
 
-- If the dialog contains semantic elements like lists or tables that are necessary to perceive in order to better understand dialog content, place focus on a static element at the start of the content
-  - The element that receives focus in this way must have `tabindex=“-1”`
 - If the dialog includes an irreversible action like deleting data, place focus on the least destructive action
 - If the dialog includes actions that simply provide additional information like `OK` or `Continue` buttons, place focus on the action that is likely to be most frequently used
-- If none of the above apply, place focus on the first focusable element
-- If placing focus on an element causes the beginning of dialog content to scroll out of view, place focus on a static element at the top instead
-  - The element that receives focus in this way must have `tabindex=“-1”`
-
+- If none of the above apply, focus is automatically placed on the close dialog button
 
+To move focus away from the close dialog button, listen for the [`open` event](https://ux.redhat.com/elements/dialog/code/#rh-dialog-apis) and move focus to the appropriate element in the lightdom via the [`focus()` method](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus).
 
 ## Touch targets
 
@@ -63,8 +68,22 @@ Only the close button and any interactive elements are selectable.
 
 ### Backdrop
 
-A dialog will not close by users clicking or tapping the backdrop or outside of the container.
+A dialog will close by users clicking or tapping the backdrop or outside of the container.
+
+
+## Accessible labels
+
+Each dialog needs an accessible name. If a dialog has a heading tag in the `header` or default slot, it will automatically be used as the accessible name of the dialog.
+
+If there is no slotted heading, users should provide an `accessible-label` attribute, the value of which will be used as the accessible name:
+
+```html
+<rh-dialog accessible-label="Page Properties" trigger="first-modal-trigger">
+  ...
+</rh-dialog>
+```
 
+If neither an `accessible-label` nor any headings exist, the accessible name of the dialog will fall back to the text of the dialog's trigger.
 
 
 ## Additional guidelines
diff --git a/elements/rh-dialog/rh-dialog.css b/elements/rh-dialog/rh-dialog.css
index f12ce32234..bd995f4621 100644
--- a/elements/rh-dialog/rh-dialog.css
+++ b/elements/rh-dialog/rh-dialog.css
@@ -1,194 +1,260 @@
 :host {
+  --rh-dialog-backdrop-background-color: rgba(3, 3, 3, 0.62);
+  --rh-dialog-overlay-background-color: transparent;
+
   display: block;
   position: relative;
-
-  --_spacer-align-top: var(--rh-space-md, 8px);
-  --_height-offset: min(var(--_spacer-align-top), var(--rh-space-3xl, 48px));
 }
 
 [hidden] {
   display: none !important;
 }
 
-section {
-  display: flex;
-  position: fixed;
-  height: 100%;
-  width: 100%;
-  top: 0;
-  left: 0;
-  align-items: center;
-  justify-content: center;
-  z-index: 500;
+.visually-hidden {
+  block-size: 1px;
+  border: 0;
+  clip: rect(0, 0, 0, 0);
+  inline-size: 1px;
+  margin: -1px;
+  overflow: hidden;
+  padding: 0;
+  position: absolute;
+  white-space: nowrap;
 }
 
-#container {
-  position: relative;
-  max-height: inherit;
+#rhds-wrapper {
+  --offset: var(--rh-space-xl, 24px);
+  --offset-top: var(--offset);
+  --offset-right: var(--offset);
+
+  display: contents;
+  font-family: var(--rh-font-family-body-text, RedHatText, 'Red Hat Text', 'Noto Sans Arabic', 'Noto Sans Hebrew', 'Noto Sans JP', 'Noto Sans KR', 'Noto Sans Malayalam', 'Noto Sans SC', 'Noto Sans TC', 'Noto Sans Thai', Helvetica, Arial, sans-serif);
 }
 
-[part='overlay'] {
+/* NOTE: @deprecated, use `::backdrop` instead. Remove for RHDS v3. */
+#overlay {
+  background-color:
+    var(--rh-dialog-overlay-background-color,
+      var(--rh-dialog-backdrop-background-color));
+  block-size: 100%;
+  inset-block-start: 0;
+  inset-inline-start: 0;
   position: fixed;
-  height: 100%;
-  width: 100%;
-  top: 0;
-  left: 0;
-  background-color: rgba(3, 3, 3, 0.62);
+  inline-size: 100%;
 }
 
-[part='dialog'] {
-  position: relative;
-  margin: 0 auto;
-  width: var(--_box-width, calc(100% - var(--rh-space-2xl, 32px)));
-  max-height: var(--_box-max-height, calc(100% - var(--rh-space-3xl, 48px)));
-  box-shadow:
-    0 1rem 2rem 0 rgba(3, 3, 3, 0.16),
-    0 0 0.5rem 0 rgba(3, 3, 3, 0.1);
-  padding: var(--rh-space-xl, 24px);
-  margin-inline: var(--rh-space-lg, 16px);
-  background-color: var(--rh-color-surface-lightest, #ffffff);
-  max-width: min(90%, 1140px);
-  border-radius: var(--rh-border-radius-default, 3px);
-  color: var(--rh-color-text-primary-on-light, #151515);
-  font-family: inherit;
+::backdrop {
+  background-color: var(--rh-dialog-backdrop-background-color);
 }
 
-:host([width]) [part='dialog'],
-:host([variant]) [part='dialog'] {
-  margin-inline: 0;
+#dialog {
+  background-color: var(--rh-color-surface);
+  border-radius: var(--rh-border-radius-default, 3px);
+  border: 0;
+  box-shadow: var(--rh-box-shadow-xl, 0 8px 24px 3px rgba(21, 21, 21, 0.35));
+  box-sizing: border-box;
+  color: var(--rh-color-text-primary);
+  font-family: inherit;
+  inline-size: 100%;
+  margin-inline: auto;
+  max-block-size: var(--_box-max-block-size, calc(100vh - var(--rh-space-3xl, 48px)));
+  max-inline-size: var(--_box-width, min(90%, 1140px));
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  padding: var(--rh-space-xl, 24px);
+  position: relative;
 }
 
-:host([width='small']) [part='dialog'],
-:host([variant='small']) [part='dialog'] {
+:host([width='small']) #dialog,
+:host([variant='small']) #dialog {
   --_box-width: 35rem;
 }
 
-:host([width='medium']) [part='dialog'],
-:host([variant='medium']) [part='dialog'] {
+:host([width='medium']) #dialog,
+:host([variant='medium']) #dialog {
   --_box-width: 52.5rem;
 }
 
-:host([width='large']) [part='dialog'],
-:host([variant='large']) [part='dialog'] {
+:host([width='large']) #dialog,
+:host([variant='large']) #dialog {
   --_box-width: 70rem;
 }
 
-[part='content'] {
-  overflow-y: auto;
-  overscroll-behavior: contain;
-  max-height: var(--_box-max-height, calc(100vh - var(--rh-space-3xl, 48px)));
-  box-sizing: border-box;
-  border-radius: var(--rh-border-radius-default, 3px);
+#content {
+  margin-block-start: calc(-1 * var(--offset-top));
 }
 
-[part='content'] ::slotted([slot='header']) {
-  margin-top: 0 !important;
-}
+#header {
+  background-color: var(--rh-color-surface);
+  inset-block-start: 0;
+  margin-block-end: var(--rh-space-lg, 16px);
+  position: relative;
 
-header {
-  position: sticky;
-  top: 0;
-  background-color: var(--rh-color-surface-lightest, #ffffff);
+  &:before {
+    background-color: var(--rh-color-surface);
+    block-size: 100%;
+    content: '';
+    inline-size: 100%;
+    inset-block-start: calc(-1 * var(--offset-top));
+    position: absolute;
+    z-index: -1;
+  }
+
+  &:after {
+    background-color: var(--rh-color-surface);
+    block-size: var(--rh-space-lg, 16px);
+    content: '';
+    inline-size: 100%;
+    position: absolute;
+    z-index: -1;
+  }
+
+  @media (min-height: 768px) {
+    position: sticky;
+  }
+
+  @media (min-width: 768px) and (min-height: 576px) {
+    position: sticky;
+  }
+
+  @media (min-width: 1200px) {
+    margin-block-end: var(--rh-space-xl, 24px);
+  }
 }
 
-header ::slotted(:is(h1,h2,h3,h4,h5,h6)[slot='header']) {
-  font-size: var(--rh-font-size-heading-sm, 1.5rem);
-  font-weight: var(--rh-font-weight-body-text-regular, 400);
-  font-family: 'Red Hat Display', RedHatDisplay, Overpass, Helvetica, sans-serif;
+#header[hidden] + #body {
+  max-inline-size: calc(100% - var(--rh-space-xl, 24px));
 }
 
-[part='close-button'] {
-  color: var(--rh-color-icon-subtle, #707070);
-  background-color: transparent;
-  border: none;
-  margin: 0;
-  padding: 0;
-  text-align: left;
-  position: absolute;
-  cursor: pointer;
-  line-height: 24px;
-  padding-block: 0.375rem;
-  padding-inline: var(--rh-space-lg, 16px);
-  top: 0;
-  right: calc(var(--rh-space-xl, 24px) / -3);
+#header,
+#header[hidden] + #body {
+  padding-inline-end: var(--rh-space-3xl, 48px);
 }
 
-[part='close-button'] > svg {
-  font-size: 16px;
-  width: var(--rh-space-lg, 16px);
-  aspect-ratio: 1/1;
+@media (min-width: 1200px) {
+  #rhds-wrapper {
+    --offset: var(--rh-space-2xl, 32px);
+  }
+
+  #dialog {
+    padding: var(--rh-space-2xl, 32px);
+  }
+
+  #content:has(#header[hidden]) {
+    --offset-top: var(--rh-space-xl, 24px);
+  }
+
+  #header[hidden] + #body {
+    max-inline-size: calc(100% - var(--rh-space-2xl, 32px));
+  }
 }
 
-[part='close-button']:is(:hover, :focus-within, :focus-visible) svg:is(svg, :hover) {
-  fill: var(--rh-color-icon-secondary-on-light, #151515);
+#content ::slotted([slot='header']) {
+  margin-top: 0 !important;
 }
 
-:host([position='top']) #dialog {
-  align-self: start;
-  margin-block: var(--rh-space-2xl, 32px);
-  margin-inline: var(--rh-space-lg, 16px);
-  width: 100%;
-  max-width: calc(100% - min(var(--rh-space-2xl, 32px) * 2, var(--rh-space-2xl, 32px)));
-  max-height: calc(100% - var(--_height-offset) - var(--_spacer-align-top));
+#header ::slotted(:is(h1,h2,h3,h4,h5,h6)[slot='header']) {
+  font-family: var(--rh-font-family-heading, RedHatDisplay, 'Red Hat Display', 'Noto Sans Arabic', 'Noto Sans Hebrew', 'Noto Sans JP', 'Noto Sans KR', 'Noto Sans Malayalam', 'Noto Sans SC', 'Noto Sans TC', 'Noto Sans Thai', Helvetica, Arial, sans-serif);
+  font-size: var(--rh-font-size-heading-sm, 1.5rem);
+  font-weight: var(--rh-font-weight-body-text-regular, 400);
 }
 
-footer {
-  display: flex;
-  align-items: center;
-  gap: var(--rh-space-md, 8px);
+#body ::slotted(p) {
+  margin-block: 0 var(--rh-space-lg, 16px) !important;
 }
 
-#rhds-wrapper {
-  display: contents;
-  font-family: 'Red Hat Text', RedHatText, Overpass, Helvetica, sans-serif;
+#body ::slotted(p:last-of-type) {
+  margin-block-end: var(--rh-space-xl, 24px) !important;
+}
 
-  --offset: var(--rh-space-md, 8px);
-  --offset-top: var(--offset);
-  --offset-right: var(--offset);
+#close-button {
+  color: var(--rh-dialog-close-button-color, var(--rh-color-icon-secondary));
+  cursor: pointer;
+  display: block;
+  inset-block-start: 0;
+  margin-inline-start: auto;
+  max-inline-size: var(--rh-length-xl, 24px);
+  position: sticky;
+  z-index: 500;
 }
 
-:host([type='video']) {
-  --rh-dialog-close-button-color: var(--rh-color-icon-secondary-on-dark, #ffffff);
+#close-button::part(button) {
+  background-color: var(--rh-color-surface);
+  block-size: var(--rh-length-xl, 24px);
+  border-radius: var(--rh-border-radius-default, 3px);
+  inline-size: var(--rh-length-xl, 24px);
 }
 
-:host([type='video']) [part='close-button'] {
-  top: var(--offset-top);
-  right: var(--offset-right);
-  padding: var(--rh-space-sm, 6px);
-  color: var(--rh-color-icon-secondary-on-dark, #ffffff);
+:host([position='top']) #dialog {
+  inline-size: 100%;
+  margin-block-start: var(--rh-space-2xl, 32px);
+  max-inline-size: var(--_box-width, calc(100% - var(--rh-space-2xl, 32px)));
 }
 
-:host([type='video']) [part='content'] {
-  overflow: hidden;
+#footer {
+  align-items: center;
+  display: flex;
+  gap: var(--rh-space-md, 8px);
 }
 
-:host([type='video'][open]) [part='overlay'] {
+:host([type='video']) {
   --_gray-90-rgb: var(--rh-color-gray-90-rgb, 31 31 31);
+  --rh-dialog-backdrop-background-color: rgb(var(--_gray-90-rgb) / var(--rh-opacity-60, 60%));
 
-  background-color: rgb(var(--_gray-90-rgb) / var(--rh-opacity-60, 60%));
+  background-color:
+    var(--rh-dialog-overlay-background-color,
+      var(--rh-dialog-backdrop-background-color));
+}
+
+:host([type='video']) #rhds-wrapper {
+  --offset: var(--rh-space-md, 8px);
 }
 
-:host([type='video'][open]) [part='dialog'] {
+:host([type='video'][open]) #dialog {
   --_aspect-ratio: var(--rh-dialog-video-aspect-ratio, 16/9);
 
   aspect-ratio: var(--_aspect-ratio);
-  max-width: min(90%, calc(90vh * var(--_aspect-ratio) + var(--offset-top)));
+  background-color: var(--rh-dialog-overlay-background-color);
+  max-inline-size:
+    var(--_box-width,
+      min(90%, calc(90vh * var(--_aspect-ratio) + var(--offset-top))));
   padding: 0;
-  margin: 0;
 }
 
-:host([type='video']) #rhds-wrapper.mobile [part='close-button'] {
+:host([type='video']) #close-button {
+  inset-inline-end: var(--offset-right);
+  inset-block-start: var(--offset-top);
+  margin-inline-end: 0;
+  position: absolute;
+}
+
+:host([type='video']) #rhds-wrapper.mobile #close-button {
   --offset-right: var(--rh-space-sm, 6px);
 }
 
-:host([type='video']) #container,
-:host([type='video']) [part='content'],
+:host([type='video']) #close-button::part(button) {
+  background-color: transparent;
+}
+
+:host([type='video']) #close-button::part(icon) {
+  color: var(--rh-dialog-close-button-color, var(--rh-color-surface));
+  filter: drop-shadow(1px 0 1px var(--rh-dialog-backdrop-background-color));
+}
+
+:host([type='video']) #content {
+  margin-block-start: 0; /* Safari fix */
+  overflow: hidden;
+  padding: 0;
+}
+
+:host([type='video']) #content,
 :host([type='video']) ::slotted(:not([slot])) {
   aspect-ratio: var(--rh-dialog-video-aspect-ratio, 16/9);
+  max-inline-size: none;
+  inline-size: 100%;
+}
 
-  /* account for a 1px descrepency between dialog and container aspect ratio */
-  width: calc(100% + 1px);
-  position: absolute;
+:host([type='video']) ::slotted(:not([slot])) {
   inset: 0;
-  max-height: none;
+  position: absolute;
 }
diff --git a/elements/rh-dialog/rh-dialog.ts b/elements/rh-dialog/rh-dialog.ts
index bb09ebd1d5..5bcc6a4dfd 100644
--- a/elements/rh-dialog/rh-dialog.ts
+++ b/elements/rh-dialog/rh-dialog.ts
@@ -14,6 +14,7 @@ import { query } from 'lit/decorators/query.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
 
 import '@rhds/elements/rh-surface/rh-surface.js';
+import '@rhds/elements/rh-button/rh-button.js';
 
 export class DialogCancelEvent extends Event {
   constructor() {
@@ -45,30 +46,31 @@ async function pauseYoutube(iframe: HTMLIFrameElement) {
  * A dialog displays important information to users without requiring them to navigate away from the page.
  * @summary Communicates information requiring user input or action
  * @fires {DialogOpenEvent} open - Fires when a user clicks on the trigger or manually opens a dialog.
- * @fires {DialogCloseEvent} close - Fires when either a user clicks on either the close button or the overlay or manually closes a dialog.
- * @fires {DialogCancelEvent} cancel
+ * @fires {DialogCloseEvent} close - Fires when either a user clicks on either the close button or manually closes a dialog.
+ * @fires {DialogCancelEvent} cancel - Fires when a user clicks outside the dialog or hits ESC on their keyboard.
  * @slot - The default slot can contain any type of content. When the header is not present this unnamed slot appear at the top of the dialog window (to the left of the close button). Otherwise it will appear beneath the header.
  * @slot header - The header is an optional slot that appears at the top of the dialog window. It should be a header tag (h2-h6).
  * @slot footer - Optional footer content. Good place to put action buttons.
- * @csspart overlay - The dialog overlay which lies under the dialog and above the page body
+ * @csspart overlay - @deprecated in favor of the backdrop pseudo-element. The dialog overlay which lies under the dialog and above the page body
  * @csspart dialog - The dialog element
  * @csspart content - The container for the dialog content
  * @csspart header - The container for the optional dialog header
  * @csspart description - The container for the optional dialog description in the header
  * @csspart close-button - The dialog's close button
  * @csspart footer - Actions footer container
- * @cssprop {<number>} --rh-dialog-video-aspect-ratio
+ * @cssprop {<number>} [--rh-dialog-video-aspect-ratio=16/9]
+ *          Aspect ratio for the video inside the dialog
  * @cssprop {<color>} [--rh-dialog-close-button-color=var(--rh-color-icon-secondary-on-dark, #ffffff)]
- *           Sets the dialog close button color.
+ *          Sets the dialog close button color.
+ * @cssprop {<color>} [--rh-dialog-backdrop-background-color=rgba(3, 3, 3, 0.62)]
+ *          Sets the background color for the native HTML dialog element's `backdrop` pseudo-element
+ * @cssprop {<color>} [--rh-dialog-overlay-background-color=transparent] @deprecated
+ *          Sets the background color for the `#overlay` `<div>`. Use `--rh-dialog-backdrop-background-color` instead.
  */
 @customElement('rh-dialog')
 export class RhDialog extends LitElement {
-  static readonly version = '{{version}}';
-
   static readonly styles = [styles];
 
-  protected static closeOnOutsideClick = true;
-
   /**
    * The `variant` controls the width of the dialog.
    * There are three options: `small`, `medium` and `large`. The default is `large`.
@@ -80,11 +82,22 @@ export class RhDialog extends LitElement {
    */
   @property({ reflect: true }) position?: 'top';
 
+  /**
+   * Use `accessible-label="My custom label"` to specify the dialog's accessible name.
+   * Defaults to the name of the dialog trigger if no attribute is set and no headings exist in the modal.
+   * See Dialog's Accessibility page for more info.
+   */
+  @property({ attribute: 'accessible-label' }) accessibleLabel?: string;
+
+  /**
+   * `open` / `open="open"` declaratively opens the dialog
+   */
   @property({ type: Boolean, reflect: true }) open = false;
 
   /** Optional ID of the trigger element */
   @property() trigger?: string;
 
+  /** Use `type="video"` to embed a video player into a dialog. */
   @property({ reflect: true }) type?: 'video';
 
   /** @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/returnValue */
@@ -92,9 +105,9 @@ export class RhDialog extends LitElement {
 
   #screenSize = new ScreenSizeController(this);
 
-  @query('#overlay') private overlay?: HTMLElement | null;
-  @query('#dialog') private dialog?: HTMLElement | null;
-  @query('#close-button') private closeButton?: HTMLElement | null;
+  @query('#dialog') private dialog!: HTMLDialogElement;
+  @query('#content') private content!: HTMLElement;
+  @query('#close-button') private closeButton!: HTMLElement;
 
   #headerId = getRandomId();
   #triggerElement: HTMLElement | null = null;
@@ -107,66 +120,67 @@ export class RhDialog extends LitElement {
 
   connectedCallback() {
     super.connectedCallback();
-    this.addEventListener('keydown', this.onKeydown);
-    this.addEventListener('click', this.onClick);
+    this.addEventListener('keydown', this.#onKeyDown);
+    this.addEventListener('click', this.#onClick);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.#triggerElement?.removeEventListener('click', this.onTriggerClick);
   }
 
   render() {
     const headerId = (this.#header || this.#headings.length) ? this.#headerId : undefined;
-    const headerLabel = this.#triggerElement ? this.#triggerElement.innerText : undefined;
+    const triggerLabel = this.#triggerElement ? this.#triggerElement.innerText : undefined;
     const hasHeader = this.#slots.hasSlotted('header');
     const hasDescription = this.#slots.hasSlotted('description');
     const hasFooter = this.#slots.hasSlotted('footer');
-
     const { mobile } = this.#screenSize;
     return html`
-      <rh-surface id="rhds-wrapper"
-                           class="${classMap({ mobile })}"
-                           color-palette="lightest">
-        <section ?hidden=${!this.open}>
-          <div id="overlay" part="overlay" ?hidden=${!this.open}></div>
-          <div id="dialog"
-               part="dialog"
-               tabindex="0"
-               role="dialog"
-               aria-labelledby=${ifDefined(headerId)}
-               aria-label=${ifDefined(headerLabel)}
-               ?hidden="${!this.open}">
-            <div id="container">
-              <div id="content" part="content" class=${classMap({ hasHeader, hasDescription, hasFooter })}>
-                <header part="header">
-                  <slot name="header"></slot>
-                  <div part="description" ?hidden=${!hasDescription}>
-                    <slot name="description"></slot>
-                  </div>
-                </header>
+      <div id="rhds-wrapper" class="${classMap({ mobile })}">
+        <!-- @deprecated: 👇 use public vars for the backdrop pseudo-element instead. -->
+        <div id="overlay"
+             part="overlay"
+             ?hidden=${!this.open}>
+        </div>
+        <rh-surface class=${classMap({ hasHeader, hasDescription, hasFooter })}
+                    ?hidden=${!this.open}
+                    color-palette="lightest">
+          <dialog id="dialog"
+                  part="dialog"
+                  aria-labelledby=${ifDefined(this.accessibleLabel ? undefined : headerId)}
+                  aria-label=${ifDefined(this.accessibleLabel ? this.accessibleLabel : (!headerId ? triggerLabel : undefined))}>
+            <rh-button variant="close"
+                       id="close-button"
+                       part="close-button"
+                       type="button"
+                       @click=${this.close}>
+              <span class="visually-hidden">Close Dialog</span>
+            </rh-button>
+            <div id="content" part="content">
+              <div id="header"
+                   part="header"
+                   ?hidden=${!hasHeader}>
+                <slot name="header"></slot>
+                <div part="description" ?hidden=${!hasDescription}>
+                  <slot name="description"></slot>
+                </div>
+              </div>
+              <div id="body" part="body">
                 <slot></slot>
-                <footer ?hidden=${!hasFooter} part="footer">
-                  <slot name="footer"></slot>
-                </footer>
               </div>
-              <button id="close-button"
-                      part="close-button"
-                      aria-label="Close dialog"
-                      @keydown=${this.onKeydown}
-                      @click=${this.close}>
-                <svg fill="currentColor" viewBox="0 0 352 512">
-                  <path d="M242.72 256l100.07-100.07c12.28-12.28 12.28-32.19 0-44.48l-22.24-22.24c-12.28-12.28-32.19-12.28-44.48 0L176 189.28 75.93 89.21c-12.28-12.28-32.19-12.28-44.48 0L9.21 111.45c-12.28 12.28-12.28 32.19 0 44.48L109.28 256 9.21 356.07c-12.28 12.28-12.28 32.19 0 44.48l22.24 22.24c12.28 12.28 32.2 12.28 44.48 0L176 322.72l100.07 100.07c12.28 12.28 32.2 12.28 44.48 0l22.24-22.24c12.28-12.28 12.28-32.19 0-44.48L242.72 256z"></path>
-                </svg>
-              </button>
+              <div id="footer"
+                   part="footer"
+                   ?hidden=${!hasFooter}>
+                <slot name="footer"></slot>
+              </div>
             </div>
-          </div>
-        </section>
-      </rh-surface>
+          </dialog>
+        </rh-surface>
+      </div>
     `;
   }
 
-  disconnectedCallback() {
-    super.disconnectedCallback();
-    this.removeEventListener('keydown', this.onKeydown);
-    this.#triggerElement?.removeEventListener('click', this.onTriggerClick);
-  }
-
   @initializer()
   protected async _init() {
     await this.updateComplete;
@@ -207,8 +221,6 @@ export class RhDialog extends LitElement {
       // This prevents background scroll
       document.body.style.overflow = 'hidden';
       await this.updateComplete;
-      // Set the focus to the container
-      this.dialog?.focus();
       this.dispatchEvent(new DialogOpenEvent(this.#triggerElement));
     } else {
       // Return scrollability
@@ -218,10 +230,6 @@ export class RhDialog extends LitElement {
 
       await this.updateComplete;
 
-      if (this.#triggerElement) {
-        this.#triggerElement.focus();
-      }
-
       this.dispatchEvent(event);
     }
   }
@@ -235,35 +243,29 @@ export class RhDialog extends LitElement {
     }
   }
 
-  @bound private onTriggerClick(event: MouseEvent) {
+  @bound private async onTriggerClick(event: MouseEvent) {
     event.preventDefault();
     this.showModal();
+    await this.updateComplete;
+    this.closeButton?.focus();
   }
 
-  @bound private onClick(event: MouseEvent) {
-    const { open, overlay, dialog } = this;
+  #onClick(event: MouseEvent) {
+    const { open, content } = this;
     if (open) {
       const path = event.composedPath();
-      const { closeOnOutsideClick } = this.constructor as typeof RhDialog;
 
-      if (closeOnOutsideClick && path.includes(overlay!) && !path.includes(dialog!)) {
+      if (!path.includes(content!)) {
         event.preventDefault();
         this.cancel();
       }
     }
   }
 
-  @bound private onKeydown(event: KeyboardEvent) {
+  #onKeyDown(event: KeyboardEvent) {
     switch (event.key) {
-      case 'Tab':
-        if (event.target === this.closeButton) {
-          event.preventDefault();
-          this.dialog?.focus();
-        }
-        return;
       case 'Escape':
       case 'Esc':
-        event.preventDefault();
         this.cancel();
         return;
       case 'Enter':
@@ -277,6 +279,7 @@ export class RhDialog extends LitElement {
 
   private async cancel() {
     this.#cancelling = true;
+    this.close();
     this.open = false;
     await this.updateComplete;
     this.#cancelling = false;
@@ -293,8 +296,13 @@ export class RhDialog extends LitElement {
    * dialog.toggle();
    * ```
    */
-  @bound toggle() {
-    this.open = !this.open;
+  toggle() {
+    if (!this.open) {
+      this.showModal();
+      this.open = true;
+    } else {
+      this.close();
+    }
   }
 
   /**
@@ -303,11 +311,12 @@ export class RhDialog extends LitElement {
    * dialog.show();
    * ```
    */
-  @bound show() {
+  show() {
+    this.dialog?.showModal();
     this.open = true;
   }
 
-  @bound showModal() {
+  showModal() {
     // TODO: non-modal mode
     this.show();
   }
@@ -319,11 +328,12 @@ export class RhDialog extends LitElement {
    *          dialog.close();
    *          ```
    */
-  @bound close(returnValue?: string) {
+  close(returnValue?: string) {
     if (typeof returnValue === 'string') {
       this.returnValue = returnValue;
     }
 
+    this.dialog?.close();
     this.open = false;
   }
 }