From 0c09617da4b3eae3d605cca90f04ef835b6c700c Mon Sep 17 00:00:00 2001
From: Chris Mills <chrisdavidmills@gmail.com>
Date: Mon, 11 Sep 2023 16:51:18 +0100
Subject: [PATCH 1/4] feat: Add content for overlay and discrete animation
 features

---
 .../web/api/cssstartingstylerule/index.md     |  33 ++
 files/en-us/web/css/@starting-style/index.md  | 283 ++++++++++++++++++
 files/en-us/web/css/overlay/index.md          | 116 +++++++
 .../web/css/transition-behavior/index.md      | 137 +++++++++
 files/en-us/web/css/transition/index.md       |  10 +-
 files/jsondata/GroupData.json                 |   1 +
 6 files changed, 579 insertions(+), 1 deletion(-)
 create mode 100644 files/en-us/web/api/cssstartingstylerule/index.md
 create mode 100644 files/en-us/web/css/@starting-style/index.md
 create mode 100644 files/en-us/web/css/overlay/index.md
 create mode 100644 files/en-us/web/css/transition-behavior/index.md

diff --git a/files/en-us/web/api/cssstartingstylerule/index.md b/files/en-us/web/api/cssstartingstylerule/index.md
new file mode 100644
index 000000000000000..ba8a7dc779da43a
--- /dev/null
+++ b/files/en-us/web/api/cssstartingstylerule/index.md
@@ -0,0 +1,33 @@
+---
+title: CSSStartingStyleRule
+slug: Web/API/CSSStartingStyleRule
+page-type: web-api-interface
+browser-compat: api.CSSStartingStyleRule
+---
+
+{{ APIRef("CSSOM") }}
+
+The **`CSSStartingStyleRule`** interface of the [CSS Object Model](/en-US/docs/Web/API/CSS_Object_Model) represents a CSS [`@starting-style`](/en-US/docs/Web/CSS/@starting-style) at-rule.
+
+{{InheritanceDiagram}}
+
+## Instance properties
+
+_This interface inherits properties from its parent, {{domxref("CSSGroupingRule")}}._
+
+## Instance methods
+
+_This interface inherits methods from its parent, {{domxref("CSSGroupingRule")}}._
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`@starting-style`](/en-US/docs/Web/CSS/@starting-style)
+- [Using dynamic styling information](/en-US/docs/Web/API/CSS_Object_Model/Using_dynamic_styling_information)
diff --git a/files/en-us/web/css/@starting-style/index.md b/files/en-us/web/css/@starting-style/index.md
new file mode 100644
index 000000000000000..846684d1772714e
--- /dev/null
+++ b/files/en-us/web/css/@starting-style/index.md
@@ -0,0 +1,283 @@
+---
+title: "@starting-style"
+slug: Web/CSS/@starting-style
+page-type: css-at-rule
+status:
+  - experimental
+browser-compat: css.at-rules.starting-style
+---
+
+{{CSSRef}}{{SeeCompatTable}}
+
+The **`@starting-style`** [CSS](/en-US/docs/Web/CSS) [at-rule](/en-US/docs/Web/CSS/At-rule) is used to provide a set of starting values for properties set on an element that you want to transition from when the element receives its first style update.
+
+This is needed because, by default, [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions) are not triggered on elements' first style updates, or when the [`display`](/en-US/docs/Web/CSS/display) type changes from `none` to another type, to avoid unexpected behavior. To put it another way, such elements do not have a starting style to transition from. `@starting-style` allows you to provide starting styles, overriding the default behavior in a specific controlled fashion.
+
+This enables the easy creation of entry animations that were previously complex to achieve, such as animating elements when they are changed from `display: none` (this includes elements shown in the [top layer](/en-US/docs/Glossary/Top_layer) such as [popovers](/en-US/docs/Web/API/Popover_API) or modal {{htmlelement("dialog")}} elements) or when they are first added to the DOM.
+
+## Syntax
+
+```css
+@starting-style {rules}
+@starting-style {declarations}
+```
+
+where:
+
+- _rules_
+  - : Is the set of CSS rules providing the starting styles for the transition, when `@starting-style` is used in standalone style.
+- _rules_
+  - : Is the set of CSS declarations providing the starting styles for the transition, when `@starting-style` is nested inside a particular ruleset.
+
+## Description
+
+There are two ways to use `@starting-style`. Let's consider an example where we want to animate a popover when it is shown (added to the top layer). In this case, the original rule specifying the styles for the popover once opened looks like this (you can see the [full example in action](/en-US/docs/Web/CSS/@starting-style#animating_a_popover) in the examples section):
+
+```css
+[popover]:popover-open {
+  opacity: 1;
+  transform: scaleX(1);
+}
+```
+
+You can specify the starting styles in a separate rule contained within a standalone `@starting-style` block:
+
+```css
+@starting-style {
+  [popover]:popover-open {
+    opacity: 0;
+    transform: scaleX(0);
+  }
+}
+```
+
+> **Note:** In the standalone case, you need to specify the `@starting-style` block after the original rule for it to take effect, as the specificity of each is the same. If `@starting-style` was specified first, the original styles would override it.
+
+Alternatively, you can nest the starting styles inside the original rule:
+
+```css
+[popover]:popover-open {
+  opacity: 1;
+  transform: scaleX(1);
+
+  @starting-style {
+    opacity: 0;
+    transform: scaleX(0);
+  }
+}
+```
+
+## Formal syntax
+
+{{csssyntax}}
+
+## Examples
+
+### Animating a popover
+
+This example shows how a [popover](/en-US/docs/Web/API/Popover_API) can be animated using [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions). Basic entry and exit animations are provided.
+
+The HTML contains a {{htmlelement("div")}} element declared as a popover using the [popover](/en-US/docs/Web/HTML/Global_attributes/popover) attribute, and a {{htmlelement("button")}} element designated as the popover's toggle control using its [popovertarget](/en-US/docs/Web/HTML/Element/button#popovertarget) attribute.
+
+```html
+<button popovertarget="mypopover">Toggle the popover</button>
+<div popover="auto" id="mypopover">I'm a Popover! I should animate.</div>
+```
+
+The CSS for the example looks like this:
+
+```css
+html {
+  font-family: Arial, Helvetica, sans-serif;
+}
+
+[popover]:popover-open {
+  opacity: 1;
+  transform: scaleX(1);
+}
+
+[popover] {
+  font-size: 1.2rem;
+  padding: 10px;
+  opacity: 0;
+  transform: scaleX(0);
+  transition:
+    opacity 0.7s,
+    transform 0.7s,
+    overlay 0.7s allow-discrete,
+    display 0.7s allow-discrete;
+}
+
+/* Needs to be included after the previous [popover]:popover-open rule
+   to take effect, as the specificity is the same */
+@starting-style {
+  [popover]:popover-open {
+    opacity: 0;
+    transform: scaleX(0);
+  }
+}
+```
+
+The two properties we want to animate are [`opacity`](/en-US/docs/Web/CSS/opacity) and [`transform`](/en-US/docs/Web/CSS/transform) (specifically, a horizontally scaling transform): we want the popover to fade in and out, as well as growing/shrinking horizontally. To achieve this, we have set a starting state for these properties on the default hidden state of the popover element (selected via `[popover]`), and an end state on the open state of the popover (selected via the [`:popover-open`](/en-US/docs/Web/CSS/:popover-open) pseudo-class).
+
+We then set a [`transition`](/en-US/docs/Web/CSS/transition) property to animate between the two, and include a starting state for the animation inside a [`@starting-style`](/en-US/docs/Web/CSS/@starting-style) at-rule, as described above, so the entry animation will work.
+
+However, because the animated element is being promoted to the [top layer](/en-US/docs/Glossary/Top_layer) when shown and removed from the top layer when hidden — which also means that its hidden state has [`display: none`](/en-US/docs/Web/CSS/display) set on it — some extra steps are required to get the animation working in both directions:
+
+- `display` is added to the list of transitioned elements so that the animated element is visible (set to `display: block`) throughout both the entry and exit animation. Without this, the exit animation would not be visible; in effect, the popover would just disappear. Note that the [`transition-behavior: allow-discrete`](/en-US/docs/Web/CSS/transition-behavior) value is also set in the shorthand so that it will animate.
+- [`overlay`](/en-US/docs/Web/CSS/overlay) is added to the list of transitioned elements to make sure that the removal of the element from the top layer is deferred until the animation has been completed. This doesn't make a huge difference for simple animations such as this one, but in more complex cases not doing this can result in the element being removed from the overlay too quickly, meaning the animation is not smooth or effective. Again, `transition-behavior: allow-discrete` is required in this case for the animation to occur.
+
+The code renders as follows:
+
+{{ EmbedLiveSample("Animating a popover", "100%", "200") }}
+
+### Transitioning elements as they are added to and removed from the DOM
+
+In this example, we provide a button that appends new elements to a {{htmlelement("section")}} container when pressed. Each element is given a nested close button which, when pressed, removes the element again. We use transitions to animate the elements when they are first added to the DOM, and when they are removed.
+
+The static HTML looks like this:
+
+```html
+<button>Create new column</button>
+<section></section>
+```
+
+The JavaScript that handles the adding and removing looks like this:
+
+```js
+const btn = document.querySelector("button");
+const sectionElem = document.querySelector("section");
+
+btn.addEventListener("click", createColumn);
+
+function randomColor() {
+  function randomChannel() {
+    return Math.floor(Math.random() * 255);
+  }
+
+  return `rgb(${randomChannel()},${randomChannel()},${randomChannel()})`;
+}
+
+function createColumn() {
+  const divElem = document.createElement("div");
+  divElem.style.backgroundColor = randomColor();
+
+  const closeBtn = document.createElement("button");
+  closeBtn.textContent = "✖";
+  closeBtn.setAttribute("aria-label", "close");
+  divElem.append(closeBtn);
+  sectionElem.append(divElem);
+
+  closeBtn.addEventListener("click", () => {
+    divElem.classList.add("fade-out");
+
+    setTimeout(() => {
+      divElem.remove();
+    }, 1000);
+  });
+}
+```
+
+The most interesting part is the `createColumn()` function — note how it creates a {{htmlelement("div")}} element and a {{htmlelement("button")}} element to close the `<div>` when pressed then appends the `<button>` to the `<div>`, and the `<div>` to the `<section>` container. We then:
+
+- Add an event listener to the close button via {{domxref("EventTarget.addEventListener", "addEventListener")}} that adds a `fade-out` class to the `<div>` (this triggers the exit animation on it)
+- Use {{domxref("setTimeout")}} to delay the removal of the `<div>` from the DOM (via {{domxref("Element.remove()")}}) until after the animation has finished.
+
+Let's move on to the CSS:
+
+```css
+html * {
+  box-sizing: border-box;
+  font-family: sans-serif;
+}
+
+body {
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+  gap: 10px;
+}
+
+body > button {
+  margin: 10px 10px 0 10px;
+}
+
+section {
+  display: flex;
+  flex: 1;
+  gap: 10px;
+  margin: 10px;
+}
+
+div {
+  flex: 1;
+  border: 1px solid gray;
+  position: relative;
+  background: linear-gradient(
+    to right,
+    rgba(255, 255, 255, 0),
+    rgba(255, 255, 255, 0.5)
+  );
+  opacity: 1;
+  transform: scaleY(1);
+
+  transition:
+    opacity 0.7s,
+    transform 0.7s,
+    display 0.7s allow-discrete;
+}
+
+/* Needs to be included after the previous div rule
+   to take effect, as the specificity is the same */
+@starting-style {
+  div {
+    opacity: 0;
+    transform: scaleY(0);
+  }
+}
+
+.fade-out {
+  opacity: 0;
+  display: none;
+  transform: scaleY(0);
+}
+
+div > button {
+  font-size: 1.6rem;
+  background: none;
+  border: 0;
+  text-shadow: 2px 1px 1px white;
+  border-radius: 15px;
+  position: absolute;
+  top: 1px;
+  right: 1px;
+  cursor: pointer;
+}
+```
+
+We want to transition [`opacity`](/en-US/docs/Web/CSS/opacity) and [`transform`](/en-US/docs/Web/CSS/transform) on each `<div>` as it is added to the DOM, and then reverse the animation as it is removed again. To do this, we:
+
+- Specify the end state of the properties we want to transition on the `div { ... }` rule.
+- Specify the starting state we would like to transition the properties from inside a `@starting-state` block.
+- Specify the exit animation inside the `.fade-out` rule — this is the class that our JavaScript applies to the `<div>` elements when their close buttons are pressed. Note that as well as setting the `opacity` and `transform` end states, we are also setting [`display: none`](/en-US/docs/Web/CSS/display) on the `<div>`s — we want them to be immediately not available when removed from the UI.
+- Specify the [`transition`](/en-US/docs/Web/CSS/display) list inside the `div { ... }` rule to get `opacity`, `transform`, and `display` animating. Note that in the case of `display`, [`transition-behavior: allow-discrete`](/en-US/docs/Web/CSS/transition-behavior) value is also set in the shorthand so that it will animate.
+
+The final result looks like this:
+
+{{ EmbedLiveSample("Transitioning elements as they are added to and removed from the DOM", "100%", "400") }}
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`overlay`](/en-US/docs/Web/CSS/overlay)
+- [`transition-behavior`](/en-US/docs/Web/CSS/transition-behavior)
+- [Four new CSS features for smooth entry and exit animations](https://developer.chrome.com/blog/entry-exit-animations/) on developer.chrome.com (2023)
+- {{domxref("CSSStartingStyleRule")}}
diff --git a/files/en-us/web/css/overlay/index.md b/files/en-us/web/css/overlay/index.md
new file mode 100644
index 000000000000000..4626d46d731e8d9
--- /dev/null
+++ b/files/en-us/web/css/overlay/index.md
@@ -0,0 +1,116 @@
+---
+title: overlay
+slug: Web/CSS/overlay
+page-type: css-property
+status:
+  - experimental
+browser-compat: css.properties.overlay
+---
+
+{{CSSRef}}{{SeeCompatTable}}
+
+The **`overlay`** [CSS](/en-US/docs/Web/CSS) property specifies whether an element appearing in the [top layer](/en-US/docs/Glossary/Top_layer) (for example, a shown [popover](/en-US/docs/Web/API/Popover_API) or modal {{htmlelement("dialog")}} element) is actually rendered in the top layer.
+
+It is important to note that `overlay` can _only_ be set by the browser — author styles cannot change the `overlay` value of any element. You can however add `overlay` to the [list of transition properties](/en-US/docs/Web/CSS/transition-property) set on an element. This causes its removal from the top layer to be deferred so it can be animated instead of disappearing immediately.
+
+> **Note:** When transitioning `overlay`, you need to set [`transition-behavior: allow-discrete`](/en-US/docs/Web/CSS/transition-behavior) on the transition so that it will animate. `overlay` animations differ from normal [discrete animations](/en-US/docs/Web/CSS/CSS_animated_properties#discrete) in that the visible (i.e. `auto`) state will always be shown for the full duration of the transition, regardless of whether it is the start or end state.
+
+## Syntax
+
+```css
+/* Keyword values */
+overlay: auto;
+overlay: none;
+```
+
+### Values
+
+- `auto`
+  - : The element is rendered in the top layer if it is promoted to the top layer.
+- `none`
+  - : The element is not rendered in the top layer.
+
+## Formal definition
+
+{{cssinfo}}
+
+## Formal syntax
+
+{{CSSSyntax}}
+
+## Examples
+
+### Animating a popover
+
+This example shows how a [popover](/en-US/docs/Web/API/Popover_API) can be animated using [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions). Basic entry and exit animations are provided.
+
+The HTML contains a {{htmlelement("div")}} element declared as a popover using the [popover](/en-US/docs/Web/HTML/Global_attributes/popover) attribute, and a {{htmlelement("button")}} element designated as the popover's toggle control using its [popovertarget](/en-US/docs/Web/HTML/Element/button#popovertarget) attribute.
+
+```html
+<button popovertarget="mypopover">Toggle the popover</button>
+<div popover="auto" id="mypopover">I'm a Popover! I should animate.</div>
+```
+
+The CSS for the example looks like this:
+
+```css
+html {
+  font-family: Arial, Helvetica, sans-serif;
+}
+
+[popover]:popover-open {
+  opacity: 1;
+  transform: scaleX(1);
+}
+
+[popover] {
+  font-size: 1.2rem;
+  padding: 10px;
+  opacity: 0;
+  transform: scaleX(0);
+  transition:
+    opacity 0.7s,
+    transform 0.7s,
+    overlay 0.7s allow-discrete,
+    display 0.7s allow-discrete;
+}
+
+/* Needs to be included after the previous [popover]:popover-open rule
+   to take effect, as the specificity is the same */
+@starting-style {
+  [popover]:popover-open {
+    opacity: 0;
+    transform: scaleX(0);
+  }
+}
+```
+
+The two properties we want to animate are [`opacity`](/en-US/docs/Web/CSS/opacity) and [`transform`](/en-US/docs/Web/CSS/transform) (specifically, a horizontally scaling transform): we want the popover to fade in and out, as well as growing/shrinking horizontally. To achieve this, we have set a starting state for these properties on the default hidden state of the popover element (selected via `[popover]`), and an end state on the open state of the popover (selected via the [`:popover-open`](/en-US/docs/Web/CSS/:popover-open) pseudo-class). We then set a [`transition`](/en-US/docs/Web/CSS/transition) property to animate between the two.
+
+However, because the animated element is being promoted to the [top layer](/en-US/docs/Glossary/Top_layer) when shown and removed from the top layer when hidden — which also means that its hidden state has [`display: none`](/en-US/docs/Web/CSS/display) set on it — some extra steps are required to get the animation working in both directions:
+
+- A starting state for the animation is set inside the [`@starting-style`](/en-US/docs/Web/CSS/@starting-style) at-rule. This is needed because by default transitions are not triggered on elements' first style updates, or when the `display` type changes from `none` to another type, to avoid unexpected behavior. `@starting-style` allows you to override that default in a specific controlled fashion. Without this, the entry animation would not occur and the popover would just appear.
+- `display` is added to the list of transitioned elements so that the animated element is visible (set to `display: block`) throughout both the entry and exit animation. Without this, the exit animation would not be visible; in effect, the popover would just disappear. Note that the [`transition-behavior: allow-discrete`](/en-US/docs/Web/CSS/transition-behavior) value is also set in the shorthand so that it will animate.
+- `overlay` is added to the list of transitioned elements to make sure that the removal of the element from the top layer is deferred until the animation has been completed. This doesn't make a huge difference for simple animations such as this one, but in more complex cases not doing this can result in the element being removed from the overlay too quickly, meaning the animation is not smooth or effective. Again, `transition-behavior: allow-discrete` is required in this case for the animation to occur.
+
+The code renders as follows:
+
+{{ EmbedLiveSample("Animating a popover", "100%", "200") }}
+
+#### Further examples
+
+Further examples (including a `<dialog>` modal animation) can be found at [Animating elements to and from the top-layer](https://developer.chrome.com/blog/entry-exit-animations/#animating-elements-to-and-from-the-top-layer).
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`@starting-style`](/en-US/docs/Web/CSS/@starting-style)
+- [`transition-behavior`](/en-US/docs/Web/CSS/transition-behavior)
+- [Four new CSS features for smooth entry and exit animations](https://developer.chrome.com/blog/entry-exit-animations/) on developer.chrome.com (2023)
diff --git a/files/en-us/web/css/transition-behavior/index.md b/files/en-us/web/css/transition-behavior/index.md
new file mode 100644
index 000000000000000..da70fb30ab86a70
--- /dev/null
+++ b/files/en-us/web/css/transition-behavior/index.md
@@ -0,0 +1,137 @@
+---
+title: transition-behavior
+slug: Web/CSS/transition-behavior
+page-type: css-property
+status:
+  - experimental
+browser-compat: css.properties.transition-behavior
+---
+
+{{CSSRef}}{{SeeCompatTable}}
+
+The **`transition-behavior`** [CSS](/en-US/docs/Web/CSS) property specifies whether transitions will be started for properties whose animation behavior is [discrete](/en-US/docs/Web/CSS/CSS_animated_properties#discrete).
+
+This is most significant in the cases of [`display`](/en-US/docs/Web/CSS/display), [`content-visibility`](/en-US/docs/Web/CSS/display), and [`overlay`](/en-US/docs/Web/CSS/overlay), the first two of which historically were not animatable at all to and from a hidden state (for example `display: none;`). The ability of these elements to be transitioned means that it is fairly easy to create entry and exit animations, where an element is transitioned to and from a hidden state (which includes elements appearing in the [top layer](/en-US/docs/Glossary/Top_layer) such as [popovers](/en-US/docs/Web/API/Popover_API) or modal {{htmlelement("dialog")}} elements), or transitioned as soon as it is added to the DOM.
+
+## Syntax
+
+```css
+/* Keyword values */
+transition-behavior: allow-discrete;
+transition-behavior: normal;
+
+/* Global values */
+transition-behavior: inherit;
+transition-behavior: initial;
+transition-behavior: revert;
+transition-behavior: revert-layer;
+transition-behavior: unset;
+```
+
+### Values
+
+- `allow-discrete`
+  - : Transitions will be started on the element for discrete animated properties.
+- `normal`
+  - : Transitions will _not_ be started on the element for discrete animated properties.
+
+## Formal definition
+
+{{cssinfo}}
+
+## Formal syntax
+
+{{CSSSyntax}}
+
+## Examples
+
+### Basic usage
+
+```css
+.card {
+  transition-property: opacity, display;
+  transition-duration: 0.25s, 0.25s;
+  transition-behavior: allow-discrete;
+}
+
+.card.fade-out {
+  opacity: 0;
+  display: none;
+}
+```
+
+See the next example for shorthand usage.
+
+### Animating a popover
+
+This example shows how a [popover](/en-US/docs/Web/API/Popover_API) can be animated using [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions). Basic entry and exit animations are provided.
+
+The HTML contains a {{htmlelement("div")}} element declared as a popover using the [popover](/en-US/docs/Web/HTML/Global_attributes/popover) attribute, and a {{htmlelement("button")}} element designated as the popover's toggle control using its [popovertarget](/en-US/docs/Web/HTML/Element/button#popovertarget) attribute.
+
+```html
+<button popovertarget="mypopover">Toggle the popover</button>
+<div popover="auto" id="mypopover">I'm a Popover! I should animate.</div>
+```
+
+The CSS for the example looks like this:
+
+```css
+html {
+  font-family: Arial, Helvetica, sans-serif;
+}
+
+[popover]:popover-open {
+  opacity: 1;
+  transform: scaleX(1);
+}
+
+[popover] {
+  font-size: 1.2rem;
+  padding: 10px;
+  opacity: 0;
+  transform: scaleX(0);
+  transition:
+    opacity 0.7s,
+    transform 0.7s,
+    overlay 0.7s allow-discrete,
+    display 0.7s allow-discrete;
+}
+
+/* Needs to be included after the previous [popover]:popover-open rule
+   to take effect, as the specificity is the same */
+@starting-style {
+  [popover]:popover-open {
+    opacity: 0;
+    transform: scaleX(0);
+  }
+}
+```
+
+The two properties we want to animate are [`opacity`](/en-US/docs/Web/CSS/opacity) and [`transform`](/en-US/docs/Web/CSS/transform) (specifically, a horizontally scaling transform): we want the popover to fade in and out, as well as growing/shrinking horizontally. To achieve this, we have set a starting state for these properties on the default hidden state of the popover element (selected via `[popover]`), and an end state on the open state of the popover (selected via the [`:popover-open`](/en-US/docs/Web/CSS/:popover-open) pseudo-class). We then set a [`transition`](/en-US/docs/Web/CSS/transition) property to animate between the two.
+
+However, because the animated element is being promoted to the [top layer](/en-US/docs/Glossary/Top_layer) when shown and removed from the top layer when hidden — which also means that its hidden state has [`display: none`](/en-US/docs/Web/CSS/display) set on it — some extra steps are required to get the animation working in both directions:
+
+- A starting state for the animation is set inside the [`@starting-style`](/en-US/docs/Web/CSS/@starting-style) at-rule. This is needed because by default transitions are not triggered on elements' first style updates, or when the `display` type changes from `none` to another type, to avoid unexpected behavior. `@starting-style` allows you to override that default in a specific controlled fashion. Without this, the entry animation would not occur and the popover would just appear.
+- `display` is added to the list of transitioned elements so that the animated element is visible (set to `display: block`) throughout both the entry and exit animation. Without this, the exit animation would not be visible; in effect, the popover would just disappear.
+- [`overlay`](/en-US/docs/Web/CSS/overlay) is added to the list of transitioned elements to make sure that the removal of the element from the top layer is deferred until the animation has been completed. This doesn't make a huge difference for simple animations such as this one, but in more complex cases not doing this can result in the element being removed from the overlay too quickly, meaning the animation is not smooth or effective.
+
+In the transitions list, `transition-behavior: allow-discrete` is set in the shorthand for both `display` and `overlay` so that they will animate.
+
+The code renders as follows:
+
+{{ EmbedLiveSample("Animating a popover", "100%", "200") }}
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`overlay`](/en-US/docs/Web/CSS/overlay)
+- [`@starting-style`](/en-US/docs/Web/CSS/@starting-style)
+- [`transition`](/en-US/docs/Web/CSS/transition)
+- [Four new CSS features for smooth entry and exit animations](https://developer.chrome.com/blog/entry-exit-animations/) on developer.chrome.com (2023)
diff --git a/files/en-us/web/css/transition/index.md b/files/en-us/web/css/transition/index.md
index 636c9530b8921cd..54f3333ce023a12 100644
--- a/files/en-us/web/css/transition/index.md
+++ b/files/en-us/web/css/transition/index.md
@@ -7,7 +7,7 @@ browser-compat: css.properties.transition
 
 {{CSSRef}}
 
-The **`transition`** [CSS](/en-US/docs/Web/CSS) property is a [shorthand property](/en-US/docs/Web/CSS/Shorthand_properties) for {{ cssxref("transition-property") }}, {{ cssxref("transition-duration") }}, {{ cssxref("transition-timing-function") }}, and {{ cssxref("transition-delay") }}.
+The **`transition`** [CSS](/en-US/docs/Web/CSS) property is a [shorthand property](/en-US/docs/Web/CSS/Shorthand_properties) for {{ cssxref("transition-property") }}, {{ cssxref("transition-duration") }}, {{ cssxref("transition-timing-function") }}, {{ cssxref("transition-delay") }}, and {{ cssxref("transition-behavior") }}.
 
 {{EmbedInteractiveExample("pages/css/transition.html")}}
 
@@ -17,6 +17,7 @@ Transitions enable you to define the transition between two states of an element
 
 This property is a shorthand for the following CSS properties:
 
+- [`transition-behavior`](/en-US/docs/Web/CSS/transition-behavior) {{experimental_inline}}
 - [`transition-delay`](/en-US/docs/Web/CSS/transition-delay)
 - [`transition-duration`](/en-US/docs/Web/CSS/transition-duration)
 - [`transition-property`](/en-US/docs/Web/CSS/transition-property)
@@ -38,6 +39,9 @@ transition: margin-right 4s ease-in-out;
 /* property name | duration | easing function | delay */
 transition: margin-right 4s ease-in-out 1s;
 
+/* property name | duration | behavior */
+transition: display 4s allow-discrete;
+
 /* Apply to 2 properties */
 transition:
   margin-right 4s,
@@ -66,6 +70,10 @@ Each single-property transition describes the transition that should be applied
 
 - zero or one {{cssxref("&lt;easing-function&gt;")}} value representing the easing function to use
 - zero, one, or two {{cssxref("&lt;time&gt;")}} values. The first value that can be parsed as a time is assigned to the {{cssxref("transition-duration")}}, and the second value that can be parsed as a time is assigned to {{cssxref("transition-delay")}}.
+- zero or one value declaring whether to start transitions for properties whose animation behavior is [discrete](/en-US/docs/Web/CSS/CSS_animated_properties#discrete):
+
+  - the keyword `allow-discrete`
+  - the keyword `normal`
 
 See [how things are handled](/en-US/docs/Web/CSS/CSS_transitions/Using_CSS_transitions#when_property_value_lists_are_of_different_lengths) when lists of property values aren't the same length. In short, extra transition descriptions beyond the number of properties actually being animated are ignored.
 
diff --git a/files/jsondata/GroupData.json b/files/jsondata/GroupData.json
index d944cebd1bd07db..938942d7f0a01f8 100644
--- a/files/jsondata/GroupData.json
+++ b/files/jsondata/GroupData.json
@@ -293,6 +293,7 @@
         "CSSRule",
         "CSSRuleList",
         "CSSStyleDeclaration",
+        "CSSStartingStyleRule",
         "CSSStyleRule",
         "CSSStyleSheet",
         "CSSSupportsRule",

From 25f6a671340b045fdd43949dceaf814bb4e61263 Mon Sep 17 00:00:00 2001
From: Chris Mills <chrisdavidmills@gmail.com>
Date: Wed, 13 Sep 2023 13:11:09 +0100
Subject: [PATCH 2/4] Add rest of required updates

---
 .../en-us/web/api/popover_api/using/index.md  | 200 +++++++++++++++-
 files/en-us/web/css/@starting-style/index.md  |   2 +
 .../en-us/web/css/content-visibility/index.md | 110 +++++++++
 .../using_css_animations/index.md             | 109 +++++++++
 .../using_css_transitions/index.md            |  92 +++++++-
 files/en-us/web/css/display/index.md          |  18 ++
 .../web/css/transition-behavior/index.md      |   2 +-
 .../web/css/transition-property/index.md      |  27 +--
 files/en-us/web/css/transition/index.md       |  28 ++-
 files/en-us/web/html/element/dialog/index.md  | 219 +++++++++++++++++-
 10 files changed, 786 insertions(+), 21 deletions(-)

diff --git a/files/en-us/web/api/popover_api/using/index.md b/files/en-us/web/api/popover_api/using/index.md
index 7d5d3d0a33e1fff..c7ba84f56ae52dd 100644
--- a/files/en-us/web/api/popover_api/using/index.md
+++ b/files/en-us/web/api/popover_api/using/index.md
@@ -301,4 +301,202 @@ The {{cssxref("::backdrop")}} pseudo-element is a full-screen element placed dir
 
 See our [Popover blur background example](https://mdn.github.io/dom-examples/popover-api/blur-background/) ([source](https://github.com/mdn/dom-examples/tree/main/popover-api/blur-background)) for an idea of how this renders.
 
-Finally, animation needs a special mention, as a lot of people are going to want to animate popovers between showing and hiding. As it stands, [a few updates to CSS behavior](https://open-ui.org/components/popover.research.explainer/#animation-of-popovers) are required to get popovers to be animatable, most notably enabling animation of elements as they move to and from `display: none`. We'll update this article as soon as animation is available for popovers.
+## Animating popovers
+
+For popovers to be animated, several different features are required.
+
+First of all, popovers are set to `display: none;` when hidden and `display: block;` when shown, as well as being removed from / added to the {{glossary("top layer")}}. Therefore, `display` needs to be animatable. This is now the case; [supporting browsers](/en-US/docs/Web/CSS/display#browser_compatibility) animate `display` with a variation on the [discrete animation type](/en-US/docs/Web/CSS/CSS_animated_properties#discrete). Specifically, the browser will flip between `none` and another value of `display` so that the animated content is shown for `100%` of the animation duration. So for example:
+
+- When animating between `display` `none` and `block`, the value will flip to `block` at `0%` of the animation duration so it is visible throughout.
+- When animating between `display` `block` and `none`, the value will flip to `none` at `100%` of the animation duration so it is visible throughout.
+
+### Transitioning a popover
+
+When animating popovers with transitions, these additional features are needed:
+
+- [`@starting-style`](/en-US/docs/Web/CSS/@starting-style) is used to provide a set of starting values for properties set on the popover that you want to transition from when it is shown. This is needed because, by default, [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions) are not triggered on elements' first style updates, or when the `display` type changes from `none` to another type, to avoid unexpected behavior.
+- [`display`](/en-US/docs/Web/CSS/display) needs to be added to the transitions list so that the popover will remain as `display: block` for the duration of the animation, allowing the other animations to be seen.
+- [`overlay`](/en-US/docs/Web/CSS/overlay) needs to be added to the transitions list so that the removal of the popover from the top layer will be deferred until the animation is finished, again allowing the other animations to be seen.
+- [`transition-behavior: allow-discrete`](/en-US/docs/Web/CSS/transition-behavior) needs to be set on the `display` and `overlay` transitions. This effectively enables discrete transitions.
+
+Let's have a look at an example so you can see what this looks like:
+
+The HTML contains a {{htmlelement("div")}} element declared as a popover, and a {{htmlelement("button")}} element designated as the popover's toggle control:
+
+```html
+<button popovertarget="mypopover">Toggle the popover</button>
+<div popover="auto" id="mypopover">I'm a Popover! I should animate.</div>
+```
+
+The CSS for the example looks like this:
+
+```css
+html {
+  font-family: Arial, Helvetica, sans-serif;
+}
+
+::backdrop {
+  background-color: rgba(0, 0, 0, 0.1);
+  transition:
+    background-color 0.5s,
+    display 0.5s allow-discrete,
+    overlay 0.5s allow-discrete;
+}
+
+@starting-style {
+  ::backdrop {
+    background-color: rgba(0, 0, 0, 0);
+  }
+}
+
+[popover]:popover-open {
+  opacity: 1;
+  transform: scaleX(1);
+}
+
+[popover] {
+  font-size: 1.2rem;
+  padding: 10px;
+  opacity: 0;
+  transform: scaleX(0);
+  transition:
+    opacity 0.7s,
+    transform 0.7s,
+    overlay 0.7s allow-discrete,
+    display 0.7s allow-discrete;
+}
+
+/* Needs to be included after the previous [popover]:popover-open rule
+   to take effect, as the specificity is the same */
+@starting-style {
+  [popover]:popover-open {
+    opacity: 0;
+    transform: scaleX(0);
+  }
+}
+```
+
+The two properties we want to show animations for are [`opacity`](/en-US/docs/Web/CSS/opacity) and [`transform`](/en-US/docs/Web/CSS/transform) (specifically, a horizontally scaling transform): we want the popover to fade in and out, as well as growing/shrinking horizontally.To achieve this, we have set a starting state for these properties on the default hidden state of the popover element (selected via `[popover]`), and an end state on the open state of the popover (selected via the [`:popover-open`](/en-US/docs/Web/CSS/:popover-open) pseudo-class). We then set a [`transition`](/en-US/docs/Web/CSS/transition) property to animate between the two.
+
+And as discussed earlier, we have:
+
+- Set a starting state for the transition inside the `@starting-style` block.
+- Added `display` to the list of transitioned elements so that the animated element is visible (set to `display: block`) throughout both the entry and exit animation. Without this, the exit animation would not be visible; in effect, the popover would just disappear.
+- Added `overlay` to the list of transitioned elements to make sure that the removal of the element from the top layer is deferred until the animation has been completed. This doesn't make a huge difference for simple animations such as this one, but in more complex cases not doing this can result in the element being removed from the overlay too quickly, meaning the animation is not smooth or effective.
+- Set `allow-discrete` on both the above transitions to enable discrete transitions.
+
+You'll note that we have also done something similar for the [`::backdrop`](/en-US/docs/Web/CSS/::backdrop) that appears behind the popover when it opens, to provide a nice darkening animation.
+
+The code renders as follows:
+
+{{ EmbedLiveSample("Transitioning a popover", "100%", "200") }}
+
+### A popover keyframe animation
+
+When animating a popover with [CSS animations](/en-US/docs/Web/CSS/CSS_animations), there are some differences to note:
+
+- You don't provide a starting state inside a `@starting-style` block; instead, you need to provide the starting `display` value in an explicit starting keyframe (for example using `0%` or `from`).
+- You don't need to enable discrete transitions; there is no equivalent to `allow-discrete` inside keyframes.
+- You can't set `overlay` inside keyframes either. The best solution we found at this time to defer removal from the top layer was to use JavaScript — animating the popover and then using {{domxref("setTimeout()")}} to defer removal of the popover until after the animation is finished.
+
+Let's look at an example. The HTML is contains a {{htmlelement("div")}} element declared as a popover, and a {{htmlelement("button")}} element designated as the popover's toggle control:
+
+```html
+<button id="toggle-button">Toggle the popover</button>
+<div popover="manual" id="mypopover">I'm a Popover! I should animate.</div>
+```
+
+The CSS is as follows:
+
+```css
+html {
+  font-family: Arial, Helvetica, sans-serif;
+}
+
+/* Transition the :backdrop when the popover is promoted to the top layer */
+::backdrop {
+  background-color: rgba(0, 0, 0, 0.1);
+  transition:
+    background-color 0.5s,
+    display 0.5s allow-discrete,
+    overlay 0.5s allow-discrete;
+}
+
+@starting-style {
+  ::backdrop {
+    background-color: rgba(0, 0, 0, 0);
+  }
+}
+
+[popover] {
+  font-size: 1.2rem;
+  padding: 10px;
+}
+
+/* Animation classes */
+
+.fade-in {
+  animation: fade-in 0.7s ease-out forwards;
+}
+
+.fade-out {
+  animation: fade-out 0.7s ease-out forwards;
+}
+
+/* Animation keyframes */
+
+@keyframes fade-in {
+  0% {
+    opacity: 0;
+    transform: scaleX(0);
+    display: none;
+  }
+
+  100% {
+    opacity: 1;
+    transform: scaleX(1);
+    display: block;
+  }
+}
+
+@keyframes fade-out {
+  0% {
+    opacity: 1;
+    transform: scaleX(1);
+    display: block;
+  }
+
+  100% {
+    opacity: 0;
+    transform: scaleX(0);
+    display: none;
+  }
+}
+```
+
+We have defined keyframes that specify the desired entry and exit animations, and assigned those to CSS classes. Note also that the animation example includes the same [`::backdrop`](/en-US/docs/Web/CSS/::backdrop) transition as the transition demo, to fade the backdrop in. This didn't seem possible to reproduce with a keyframe animation.
+
+We then use some rudimentary JavaScript to apply those classes to the popover as it is shown and hidden, triggering the animations at the right times. As mentioned earlier, we have used `setTimeout()` to defer the hiding of the popover until the animations have finished.
+
+```js
+const popover = document.getElementById("mypopover");
+const toggleBtn = document.getElementById("toggle-button");
+
+toggleBtn.addEventListener("click", () => {
+  if (!popover.matches(":popover-open")) {
+    popover.classList.remove("fade-out");
+    popover.classList.add("fade-in");
+    popover.showPopover();
+  } else if (popover.matches(":popover-open")) {
+    popover.classList.remove("fade-in");
+    popover.classList.add("fade-out");
+    setTimeout(() => {
+      popover.hidePopover();
+    }, 700);
+  }
+});
+```
+
+The code renders as follows:
+
+{{ EmbedLiveSample("A popover keyframe animation", "100%", "200") }}
diff --git a/files/en-us/web/css/@starting-style/index.md b/files/en-us/web/css/@starting-style/index.md
index 846684d1772714e..d7ff28b1c9e88f8 100644
--- a/files/en-us/web/css/@starting-style/index.md
+++ b/files/en-us/web/css/@starting-style/index.md
@@ -15,6 +15,8 @@ This is needed because, by default, [CSS transitions](/en-US/docs/Web/CSS/CSS_tr
 
 This enables the easy creation of entry animations that were previously complex to achieve, such as animating elements when they are changed from `display: none` (this includes elements shown in the [top layer](/en-US/docs/Glossary/Top_layer) such as [popovers](/en-US/docs/Web/API/Popover_API) or modal {{htmlelement("dialog")}} elements) or when they are first added to the DOM.
 
+> **Note:** `@starting-style` is only relevant to CSS transitions. When animating from `display: none` or animating elements as they are first added to the DOM, [CSS animations](/en-US/docs/Web/CSS/CSS_animations) do not need a `@starting-style` specified; instead you provide the starting style as an explicit starting keyframe (for example using `0%` or `from`). See [Using CSS animations](/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations) for an example.
+
 ## Syntax
 
 ```css
diff --git a/files/en-us/web/css/content-visibility/index.md b/files/en-us/web/css/content-visibility/index.md
index f2ffe3181b58d54..92a4ff2c5faee06 100644
--- a/files/en-us/web/css/content-visibility/index.md
+++ b/files/en-us/web/css/content-visibility/index.md
@@ -38,6 +38,24 @@ content-visibility: unset;
 - `auto`
   - : The element turns on layout containment, style containment, and paint containment. If the element is not [relevant to the user](/en-US/docs/Web/CSS/CSS_containment#relevant_to_the_user), it also skips its contents. Unlike hidden, the skipped contents must still be available as normal to user-agent features such as find-in-page, tab order navigation, etc., and must be focusable and selectable as normal.
 
+## Animating content-visibility
+
+Historically, the `content-visibility` property was not animatable/transitionable. The spec changed however, and [supporting browsers](#browser_compatibility) now animate `content-visibility` with a variation on the [discrete animation type](/en-US/docs/Web/CSS/CSS_animated_properties#discrete). Discrete animation generally means that the property will flip between two values `50%` through animating between the two.
+
+In the case of `content-visibility` however, the browser will flip between the two values so that the animated content is shown for `100%` of the animation duration. So for example:
+
+- When animating between `content-visibility` `hidden` and `visible`, the value will flip to `visible` at `0%` of the animation duration so it is visible throughout.
+- When animating between `content-visibility` `visible` and `hidden`, the value will flip to `hidden` at `100%` of the animation duration so it is visible throughout.
+
+This behavior is useful for creating entry/exit animations where you want to for example remove some content from the UI immediately with `content-visibility: hidden`, but have it animate (for example fade out) rather than disappearing immediately.
+
+When animating `content-visibility` with [CSS animations](/en-US/docs/Web/CSS/CSS_animations), you need to provide the starting `content-visibility` value in an explicit starting keyframe (for example using `0%` or `from`). For a full example, see the [content-visibility animation example](#content-visibility_animation_example) section below.
+
+When animating `content-visibility` with transitions, two additional features are needed:
+
+- [`@starting-style`](/en-US/docs/Web/CSS/@starting-style) is used to provide a set of starting values for properties set on an element that you want to transition from when the element receives its first style update. This is needed because, by default, [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions) are not triggered on elements' first style updates, or when the `content-visibility` value changes from `hidden` to `visible`, to avoid unexpected behavior.
+- [`transition-behavior: allow-discrete`](/en-US/docs/Web/CSS/transition-behavior) needs to be set on `content-visibility` when it is transitioned. This effectively enables `content-visibility` transitions, enabling it to animate.
+
 ## Formal definition
 
 {{cssinfo}}
@@ -149,6 +167,98 @@ document.querySelectorAll("button.toggle").forEach((button) => {
 
 {{ EmbedLiveSample('Using hidden to manually manage visibility') }}
 
+### content-visibility animation example
+
+In this example, we have a {{htmlelement("div")}} element, the content of which can be toggled between shown and hidden by clicking or pressing any key. The HTML looks like this:
+
+```html
+<p>
+  Click anywhere on the screen or press any key to toggle the
+  <code>&lt;div&gt;</code> content between hidden and showing.
+</p>
+
+<div>
+  This is a <code>&lt;div&gt;</code> element that animates between
+  <code>content-visibility: hidden;</code>and
+  <code>content-visibility: visible;</code>. We've also animated the text color
+  to provide a smooth animation effect.
+</div>
+```
+
+In the CSS we initially set `content-visibility: hidden;` on the `<div>` to hide its content. We then set up `@keyframe` animations and attach them to classes to show and hide the `<div>`, animating `content-visibility` but also [`color`](/en-US/docs/Web/CSS/color) so that you get a smooth animation effect as the content is shown/hidden.
+
+```css
+div {
+  font-size: 1.6rem;
+  padding: 20px;
+  border: 3px solid red;
+  border-radius: 20px;
+  width: 480px;
+
+  content-visibility: hidden;
+}
+
+/* Animation classes */
+
+.show {
+  animation: show 0.7s ease-in forwards;
+}
+
+.hide {
+  animation: hide 0.7s ease-out forwards;
+}
+
+/* Animation keyframes */
+
+@keyframes show {
+  0% {
+    content-visibility: hidden;
+    color: rgba(0, 0, 0, 0);
+  }
+
+  100% {
+    content-visibility: visible;
+    color: rgba(0, 0, 0, 1);
+  }
+}
+
+@keyframes hide {
+  0% {
+    content-visibility: visible;
+    color: rgba(0, 0, 0, 1);
+  }
+
+  100% {
+    content-visibility: hidden;
+    color: rgba(0, 0, 0, 0);
+  }
+}
+```
+
+Finally, we use some JavaScript to apply the `.show` and `.hide` classes to the `<div>` as appropriate to apply the animations as it is toggled between shown and hidden.
+
+```js
+const divElem = document.querySelector("div");
+const htmlElem = document.querySelector(":root");
+
+htmlElem.addEventListener("click", showHide);
+document.addEventListener("keydown", showHide);
+
+function showHide() {
+  if (divElem.classList[0] === "show") {
+    divElem.classList.remove("show");
+    divElem.classList.add("hide");
+  } else {
+    divElem.classList.remove("hide");
+    divElem.classList.add("show");
+  }
+}
+```
+
+The rendered result looks like this:
+
+{{ EmbedLiveSample("content-visibility animation example", "100%", "250") }}
+
 ## Specifications
 
 {{Specifications}}
diff --git a/files/en-us/web/css/css_animations/using_css_animations/index.md b/files/en-us/web/css/css_animations/using_css_animations/index.md
index 28e6f88f336083a..1e871224cda9a89 100644
--- a/files/en-us/web/css/css_animations/using_css_animations/index.md
+++ b/files/en-us/web/css/css_animations/using_css_animations/index.md
@@ -36,6 +36,8 @@ The sub-properties of the {{cssxref("animation")}} property are:
   - : Specifies the name of the {{cssxref("@keyframes")}} at-rule describing an animation's keyframes.
 - {{cssxref("animation-play-state")}}
   - : Specifies whether to pause or play an animation sequence.
+- {{cssxref("animation-timeline")}} {{experimental_inline}}
+  - : Specifies the timeline that is used to control the progress of a CSS animation.
 - {{cssxref("animation-timing-function")}}
   - : Specifies how an animation transitions through keyframes by establishing acceleration curves.
 
@@ -381,6 +383,113 @@ And here's the live output.
 
 {{EmbedLiveSample('Using_animation_events', '600', '300')}}
 
+## Animating display and content-visibility
+
+Historically, the [`display`](/en-US/docs/Web/CSS/display) and [`content-visibility`](/en-US/docs/Web/CSS/content-visibility) properties were not animatable. The specs changed however, and supporting browsers (see the reference links for details) now animate them with a [discrete animation type](/en-US/docs/Web/CSS/CSS_animated_properties#discrete). This generally means that properties will flip between two values `50%` through animating between the two.
+
+There is an exception, however, which is when animating to/from `display: none` or `content-visibility: hidden`. In this case, the browser will flip between the two values so that the animated content is shown for `100%` of the animation duration.
+
+So for example:
+
+- When animating between `display` `none` and `block`, the value will flip to `block` at `0%` of the animation duration so it is visible throughout.
+- When animating between `display` `block` and `none`, the value will flip to `none` at `100%` of the animation duration so it is visible throughout.
+
+This behavior is useful for creating entry/exit animations where you want to for example remove a container from the UI immediately with `display: none`, but have it fade out with [`opacity`](/en-US/docs/Web/CSS/opacity) rather than disappearing immediately.
+
+Let's put all of this together into a working example. The HTML contains a simple instruction message plus a {{htmlelement("div")}} that we will animate from `display` `none` to `block`.
+
+```html
+<p>
+  Click anywhere on the screen or press any key to toggle the
+  <code>&lt;div&gt;</code> between hidden and showing.
+</p>
+
+<div>
+  This is a <code>&lt;div&gt;</code> element that animates between
+  <code>display: none; opacity: 0</code> and
+  <code>display: block; opacity: 1</code>. Neat, huh?
+</div>
+```
+
+The CSS is as follows:
+
+```css
+html {
+  height: 100vh;
+}
+
+div {
+  font-size: 1.6rem;
+  padding: 20px;
+  border: 3px solid red;
+  border-radius: 20px;
+  width: 480px;
+  opacity: 0;
+}
+
+/* Animation classes */
+
+div.fade-in {
+  animation: fade-in 0.7s ease-in forwards;
+}
+
+div.fade-out {
+  animation: fade-out 0.7s ease-out forwards;
+}
+
+/* Animation keyframes */
+
+@keyframes fade-in {
+  0% {
+    opacity: 0;
+    display: none;
+  }
+
+  100% {
+    opacity: 1;
+    display: block;
+  }
+}
+
+@keyframes fade-out {
+  0% {
+    opacity: 1;
+    display: block;
+  }
+
+  100% {
+    opacity: 0;
+    display: none;
+  }
+}
+```
+
+Note the inclusion of the `display` property in the keyframe animations. When animating `display` or `content-visibility`, you need to provide the starting value in an explicit starting keyframe (for example using `0%` or `from`).
+
+Finally, we include a bit of JavaScript to set up event listeners to trigger the animations. Specifically, we add the `fade-in` class to the `<div>` when we want it to appear, and `fade-out` when we want it to disappear.
+
+```js
+const divElem = document.querySelector("div");
+const htmlElem = document.querySelector(":root");
+
+htmlElem.addEventListener("click", showHide);
+document.addEventListener("keydown", showHide);
+
+function showHide() {
+  if (divElem.classList[0] === "fade-in") {
+    divElem.classList.remove("fade-in");
+    divElem.classList.add("fade-out");
+  } else {
+    divElem.classList.remove("fade-out");
+    divElem.classList.add("fade-in");
+  }
+}
+```
+
+The code renders as follows:
+
+{{ EmbedLiveSample("Animating display and content-visibility", "100%", "250") }}
+
 ## See also
 
 - {{domxref("AnimationEvent", "AnimationEvent")}}
diff --git a/files/en-us/web/css/css_transitions/using_css_transitions/index.md b/files/en-us/web/css/css_transitions/using_css_transitions/index.md
index 92e8f37e82b32d1..7007acca52b18e4 100644
--- a/files/en-us/web/css/css_transitions/using_css_transitions/index.md
+++ b/files/en-us/web/css/css_transitions/using_css_transitions/index.md
@@ -46,7 +46,7 @@ div {
 
 ## Examples
 
-### Simple example
+### Basic example
 
 This example performs a four-second font size transition with a two-second delay between the time the user mouses over the element and the beginning of the animation effect:
 
@@ -258,6 +258,96 @@ el.addEventListener("transitionstart", signalStart, true);
 
 > **Note:** The `transitionend` event doesn't fire if the transition is aborted before the transition is completed because either the element is made {{cssxref("display")}}`: none` or the animating property's value is changed.
 
+## Transitioning display and content-visibility
+
+Historically, the [`display`](/en-US/docs/Web/CSS/display) and [`content-visibility`](/en-US/docs/Web/CSS/content-visibility) properties were not transitionable. The specs changed however, and supporting browsers (see the reference links for details) now animate them with a [discrete animation type](/en-US/docs/Web/CSS/CSS_animated_properties#discrete). This generally means that properties will flip between two values `50%` through animating between the two.
+
+There is an exception, however, which is when animating to/from `display: none` or `content-visibility: hidden`. In this case, the browser will flip between the two values so that the transitioned content is shown for `100%` of the animation duration.
+
+So for example:
+
+- When animating between `display` `none` and `block`, the value will flip to `block` at `0%` of the transition duration so it is visible throughout.
+- When animating between `display` `block` and `none`, the value will flip to `none` at `100%` of the transition duration so it is visible throughout.
+
+This behavior is useful for creating entry/exit animations where you want to for example remove a container from the UI immediately with `display: none`, but have it fade out with [`opacity`](/en-US/docs/Web/CSS/opacity) rather than disappearing immediately.
+
+When transitioning these properties, two additional features are also needed:
+
+- [`@starting-style`](/en-US/docs/Web/CSS/@starting-style) is used to provide a set of starting values for properties set on an element that you want to transition from when the element receives its first style update. This is needed because, by default, CSS transitions are not triggered on elements' first style updates, or when `display`/`content-visibility` changes from `none`/`hidden` to another state, to avoid unexpected behavior.
+- [`transition-behavior: allow-discrete`](/en-US/docs/Web/CSS/transition-behavior) needs to be set on the transitions. This effectively enables `display`/`content-visibility` transitions, enabling them to animate.
+
+Let's put all of this together into a working example. The HTML contains a simple instruction message plus a {{htmlelement("div")}} that we will transition from `display` `none` to `block`.
+
+```html
+<p>
+  Click anywhere on the screen or press any key to toggle the
+  <code>&lt;div&gt;</code> between hidden and showing.
+</p>
+
+<div>
+  This is a <code>&lt;div&gt;</code> element with
+  <code>display: none; opacity: 0</code> set on it initially. When it appears,
+  it transitions to <code>display: block; opacity: 1</code>. Neat, huh?
+</div>
+```
+
+The CSS is as follows:
+
+```css
+html {
+  height: 100vh;
+}
+
+div {
+  font-size: 1.6rem;
+  padding: 20px;
+  border: 3px solid red;
+  border-radius: 20px;
+  width: 480px;
+
+  display: none;
+  opacity: 0;
+  transition:
+    opacity 1s,
+    display 1s allow-discrete;
+}
+
+.showing {
+  opacity: 1;
+  display: block;
+}
+
+@starting-style {
+  .showing {
+    opacity: 0;
+  }
+}
+```
+
+Note the `@starting-style` block used to specify the starting style for the transition, and the inclusion of the `display` property in the trainsitions list, with `allow-discrete` set on it.
+
+Finally, we include a bit of JavaScript to set up event listeners to trigger the transition (via the `showing` class).
+
+```js
+const divElem = document.querySelector("div");
+const htmlElem = document.querySelector(":root");
+
+htmlElem.addEventListener("click", showHide);
+document.addEventListener("keydown", showHide);
+
+function showHide() {
+  if (divElem.classList[0] === "showing") {
+    divElem.classList.remove("showing");
+  } else {
+    divElem.classList.add("showing");
+  }
+}
+```
+
+The code renders as follows:
+
+{{ EmbedLiveSample("Transitioning display and content-visibility", "100%", "250") }}
+
 ## Specifications
 
 {{Specifications}}
diff --git a/files/en-us/web/css/display/index.md b/files/en-us/web/css/display/index.md
index bf3ed7dbbb642ca..ada34f1245677d8 100644
--- a/files/en-us/web/css/display/index.md
+++ b/files/en-us/web/css/display/index.md
@@ -259,6 +259,24 @@ The individual pages for the different types of value that `display` can have se
 - [CSS Grid Layout and Progressive Enhancement](/en-US/docs/Web/CSS/CSS_grid_layout/Grid_layout_and_progressive_enhancement)
 - [Realizing common layouts using grids](/en-US/docs/Web/CSS/CSS_grid_layout/Realizing_common_layouts_using_grids)
 
+### Animating display
+
+Historically, the `display` property was not animatable/transitionable. The spec changed however, and [supporting browsers](#browser_compatibility) now animate `display` with a [discrete animation type](/en-US/docs/Web/CSS/CSS_animated_properties#discrete). This generally means that the property will flip between two values `50%` through animating between the two.
+
+There is one exception, which is when animating to or from `display: none`. In this case, the browser will flip between the two values so that the animated content is shown for `100%` of the animation duration. So for example:
+
+- When animating between `display` `none` and `block`, the value will flip to `block` at `0%` of the animation duration so it is visible throughout.
+- When animating between `display` `block` and `none`, the value will flip to `none` at `100%` of the animation duration so it is visible throughout.
+
+This behavior is useful for creating entry/exit animations where you want to for example remove a container from the UI immediately with `display: none`, but have it fade out with [`opacity`](/en-US/docs/Web/CSS/opacity) rather than disappearing immediately.
+
+When animating `display` with [CSS animations](/en-US/docs/Web/CSS/CSS_animations), you need to provide the starting `display` value in an explicit starting keyframe (for example using `0%` or `from`). See [Using CSS animations](/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations) for an example.
+
+When animating `display` with transitions, two additional features are needed (see the below links for examples):
+
+- [`@starting-style`](/en-US/docs/Web/CSS/@starting-style) is used to provide a set of starting values for properties set on an element that you want to transition from when the element receives its first style update. This is needed because, by default, [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions) are not triggered on elements' first style updates, or when the `display` type changes from `none` to another type, to avoid unexpected behavior.
+- [`transition-behavior: allow-discrete`](/en-US/docs/Web/CSS/transition-behavior) needs to be set on `display` when it is transitioned. This effectively enables `display` transitions, enabling it to animate.
+
 ## Accessibility concerns
 
 ### display: none
diff --git a/files/en-us/web/css/transition-behavior/index.md b/files/en-us/web/css/transition-behavior/index.md
index da70fb30ab86a70..e2d47a0e034ae73 100644
--- a/files/en-us/web/css/transition-behavior/index.md
+++ b/files/en-us/web/css/transition-behavior/index.md
@@ -11,7 +11,7 @@ browser-compat: css.properties.transition-behavior
 
 The **`transition-behavior`** [CSS](/en-US/docs/Web/CSS) property specifies whether transitions will be started for properties whose animation behavior is [discrete](/en-US/docs/Web/CSS/CSS_animated_properties#discrete).
 
-This is most significant in the cases of [`display`](/en-US/docs/Web/CSS/display), [`content-visibility`](/en-US/docs/Web/CSS/display), and [`overlay`](/en-US/docs/Web/CSS/overlay), the first two of which historically were not animatable at all to and from a hidden state (for example `display: none;`). The ability of these elements to be transitioned means that it is fairly easy to create entry and exit animations, where an element is transitioned to and from a hidden state (which includes elements appearing in the [top layer](/en-US/docs/Glossary/Top_layer) such as [popovers](/en-US/docs/Web/API/Popover_API) or modal {{htmlelement("dialog")}} elements), or transitioned as soon as it is added to the DOM.
+This is most significant in the cases of [`display`](/en-US/docs/Web/CSS/display), [`content-visibility`](/en-US/docs/Web/CSS/display), and [`overlay`](/en-US/docs/Web/CSS/overlay), the first two of which historically were not animatable. The ability of these elements to be transitioned means that it is fairly easy to create entry and exit animations, where an element is transitioned to and from a hidden state (which includes elements appearing in the [top layer](/en-US/docs/Glossary/Top_layer) such as [popovers](/en-US/docs/Web/API/Popover_API) or modal {{htmlelement("dialog")}} elements), or transitioned as soon as it is added to the DOM.
 
 ## Syntax
 
diff --git a/files/en-us/web/css/transition-property/index.md b/files/en-us/web/css/transition-property/index.md
index 2d21e5c3b12b1e3..8169c4e5cd2e935 100644
--- a/files/en-us/web/css/transition-property/index.md
+++ b/files/en-us/web/css/transition-property/index.md
@@ -60,33 +60,34 @@ transition-property: unset;
 
 ## Examples
 
-### Simple example
+> **Note:** See our [Using CSS transitions](/en-US/docs/Web/CSS/CSS_transitions/Using_CSS_transitions) guide for more `transition-property` examples.
 
-This example performs a four-second font size transition when the user hovers over the element, the `transition-property` is the `font-size`.
+### Basic example
 
-#### HTML
+When the button is hovered or focused, it undergoes a one-second opacity transition; the `transition-property` is [`opacity`](/en-US/docs/Web/CSS/opacity).
+
+The HTML looks like this:
 
 ```html
-<a class="target">Hover over me</a>
+<button class="target">Focus me!</button>
 ```
 
-#### CSS
+The CSS is as follows:
 
 ```css
 .target {
-  font-size: 14px;
-  transition-property: font-size;
-  transition-duration: 4s;
+  font-size: 20px;
+  transition-property: opacity;
+  transition-duration: 1s;
 }
 
-.target:hover {
-  font-size: 36px;
+.target:hover,
+.target:focus {
+  opacity: 0;
 }
 ```
 
-{{EmbedLiveSample('Simple_example', 600, 100)}}
-
-You will find more examples of `transition-property` included in the main [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions/Using_CSS_transitions) article.
+{{EmbedLiveSample('Basic_example', 600, 100)}}
 
 ## Specifications
 
diff --git a/files/en-us/web/css/transition/index.md b/files/en-us/web/css/transition/index.md
index 54f3333ce023a12..27be632bb1e5f64 100644
--- a/files/en-us/web/css/transition/index.md
+++ b/files/en-us/web/css/transition/index.md
@@ -87,7 +87,9 @@ See [how things are handled](/en-US/docs/Web/CSS/CSS_transitions/Using_CSS_trans
 
 ## Examples
 
-### Simple example
+> **Note:** See our [Using CSS transitions](/en-US/docs/Web/CSS/CSS_transitions/Using_CSS_transitions) guide for more `transition` examples.
+
+### Basic example
 
 In this example, when the user hovers over the element, there is a one-second delay before the four-second `font-size` transition occurs.
 
@@ -112,9 +114,29 @@ We include two {{cssxref("time")}} values. In the `transition` shorthand, the fi
 }
 ```
 
-{{EmbedLiveSample('Simple_example', 600, 100)}}
+{{EmbedLiveSample('Basic_example', 600, 100)}}
+
+### Transitioning top layer elements
+
+The [`overlay`](/en-US/docs/Web/CSS/overlay) property can be added to the list of transition properties set on an element displayed in the [top layer](/en-US/docs/Glossary/Top_layer) — for example a [popover](/en-US/docs/Web/API/Popover_API) or modal {{htmlelement("dialog")}} element. This causes its removal from the top layer to be deferred so it can be animated instead of disappearing immediately.
+
+Sample CSS:
+
+```css
+[popover] {
+  font-size: 1.2rem;
+  padding: 10px;
+  opacity: 0;
+  transform: scaleX(0);
+  transition:
+    opacity 0.7s,
+    transform 0.7s,
+    overlay 0.7s allow-discrete,
+    display 0.7s allow-discrete;
+}
+```
 
-There are several more examples of CSS transitions included in the [Using CSS transitions](/en-US/docs/Web/CSS/CSS_transitions/Using_CSS_transitions) article.
+See the [`overlay`](/en-US/docs/Web/CSS/overlay) page for a full working example.
 
 ## Specifications
 
diff --git a/files/en-us/web/html/element/dialog/index.md b/files/en-us/web/html/element/dialog/index.md
index 23e8e4c434b122f..44a62a166a4e00e 100644
--- a/files/en-us/web/html/element/dialog/index.md
+++ b/files/en-us/web/html/element/dialog/index.md
@@ -36,7 +36,7 @@ The `<dialog>` element is exposed by browsers similarly to custom dialogs using
 
 ## Examples
 
-### Simple example
+### Basic example
 
 The following will render a non-modal, or modal-less, dialog. The "OK" button allows the dialog to be closed when activated.
 
@@ -51,7 +51,7 @@ The following will render a non-modal, or modal-less, dialog. The "OK" button al
 
 #### Result
 
-{{EmbedLiveSample("Simple_example", "100%", 200)}}
+{{EmbedLiveSample("Basic_example", "100%", 200)}}
 
 Because this dialog was opened via the `open` attribute, it is non-modal. In this example, when the dialog is dismissed, no method is provided to re-open it. Opening dialogs via {{domxref("HTMLDialogElement.show()")}} is preferred over the toggling of the boolean `open` attribute.
 
@@ -132,6 +132,221 @@ Without an `action`, submitting the form via the default {{HTTPMethod("GET")}} m
 
 It is important to provide a closing mechanism within every `dialog` element. The <kbd>Esc</kbd> key does not close non-modal dialogs by default, nor can one assume that a user will even have access to a physical keyboard (e.g., someone using a touch screen device without access to a keyboard).
 
+### Animating dialogs
+
+For `<dialog>` elements to be animated, several different features are required.
+
+First of all, `<dialog>`s are set to `display: none;` when hidden and `display: block;` when shown, as well as being removed from / added to the {{glossary("top layer")}}. Therefore, `display` needs to be animatable. This is now the case; [supporting browsers](/en-US/docs/Web/CSS/display#browser_compatibility) animate `display` with a variation on the [discrete animation type](/en-US/docs/Web/CSS/CSS_animated_properties#discrete). Specifically, the browser will flip between `none` and another value of `display` so that the animated content is shown for `100%` of the animation duration. So for example:
+
+- When animating between `display` `none` and `block`, the value will flip to `block` at `0%` of the animation duration so it is visible throughout.
+- When animating between `display` `block` and `none`, the value will flip to `none` at `100%` of the animation duration so it is visible throughout.
+
+#### Transitioning dialog elements
+
+When animating `<dialog>`s with [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions), these additional features are needed:
+
+- [`@starting-style`](/en-US/docs/Web/CSS/@starting-style) is used to provide a set of starting values for properties set on the `<dialog>` that you want to transition from when it is shown. This is needed because, by default, [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions) are not triggered on elements' first style updates, or when the `display` type changes from `none` to another type, to avoid unexpected behavior.
+- [`display`](/en-US/docs/Web/CSS/display) needs to be added to the transitions list so that the `<dialog>` will remain as `display: block` for the duration of the animation, allowing the other animations to be seen.
+- [`overlay`](/en-US/docs/Web/CSS/overlay) needs to be added to the transitions list so that the removal of the `<dialog>` from the top layer will be deferred until the animation is finished, again allowing the other animations to be seen.
+- [`transition-behavior: allow-discrete`](/en-US/docs/Web/CSS/transition-behavior) needs to be set on the `display` and `overlay` transitions. This effectively enables discrete transitions.
+
+Here is a quick example to show what this might look like.
+
+The HTML contains a `<dialog>` element, plus a button to show the dialog. Additionally, the `<dialog>` element contains another button to close itself.
+
+```html
+<dialog id="dialog">
+  Content here
+  <button class="close">close</button>
+</dialog>
+
+<button class="show">Show Modal</button>
+```
+
+The CSS is as follows:
+
+```css
+/* Open state of the dialog */
+dialog[open] {
+  opacity: 1;
+  transform: scaleY(1);
+}
+
+/* Closed state of the dialog */
+dialog {
+  transition:
+    opacity 0.5s ease-out,
+    transform 0.5s ease-out,
+    overlay 0.5s ease-out allow-discrete,
+    display 0.5s ease-out allow-discrete;
+  opacity: 0;
+  transform: scaleY(0);
+}
+
+/* Before-open state  */
+/* Needs to be after the previous dialog[open] rule to take effect,
+   as the specificity is the same */
+@starting-style {
+  dialog[open] {
+    opacity: 0;
+    transform: scaleY(0);
+  }
+}
+
+/* Transition the :backdrop when the dialog modal is promoted to the top layer */
+::backdrop {
+  background-color: rgba(0, 0, 0, 0.1);
+  transition:
+    background-color 0.5s,
+    display 0.5s allow-discrete,
+    overlay 0.5s allow-discrete;
+}
+
+@starting-style {
+  ::backdrop {
+    background-color: rgba(0, 0, 0, 0);
+  }
+}
+
+body,
+button {
+  font-family: system-ui;
+}
+```
+
+Note the `@starting-style` block used to define the transition starting styles, and the `display` and `overlay` properties included in the transition list, each with `allow-discrete` set on them. Note that we've also included similar CSS to transition the [`::backdrop`](/en-US/docs/Web/CSS/::backdrop) that appears behind the `<dialog>` when it opens, to provide a nice darkening animation.
+
+The JavaScript serves to wire up the buttons to event handlers that show and close the `<dialog>`:
+
+```js
+const dialogElem = document.getElementById("dialog");
+const showBtn = document.querySelector(".show");
+const closeBtn = document.querySelector(".close");
+
+showBtn.addEventListener("click", () => {
+  dialogElem.showModal();
+});
+
+closeBtn.addEventListener("click", () => {
+  dialogElem.close();
+});
+```
+
+The code renders as follows:
+
+{{ EmbedLiveSample("Transitioning dialog elements", "100%", "200") }}
+
+#### dialog keyframe animations
+
+When animating a `<dialog>` with [CSS animations](/en-US/docs/Web/CSS/CSS_animations), there are some differences to note from transitions:
+
+- You don't provide a starting state inside a `@starting-style` block; instead, you need to provide the starting `display` value in an explicit starting keyframe (for example using `0%` or `from`).
+- You don't need to enable discrete transitions; there is no equivalent to `allow-discrete` inside keyframes.
+- You can't set `overlay` inside keyframes either. The best solution we found at this time to defer removal from the top layer was to use JavaScript — animating the `<dialog>` and then using {{domxref("setTimeout()")}} to defer removal of the `<dialog>` until after the animation is finished.
+
+Let's have a look at an example so you can see what this looks like. First, the HTML contains a `<dialog>` element, plus a button to show the dialog. Additionally, the `<dialog>` element contains another button to close itself. The `<dialog>` has a `class` of `fade-in` set on it, which will trigger the entry animation when the dialog is shown.
+
+```html
+<dialog id="dialog" class="fade-in">
+  Content here
+  <button class="close">close</button>
+</dialog>
+
+<button class="show">Show Modal</button>
+```
+
+Now for the CSS:
+
+```css
+/* Animation classes */
+
+.fade-in {
+  animation: fade-in 0.5s ease-out forwards;
+}
+
+.fade-out {
+  animation: fade-out 0.5s ease-out forwards;
+}
+
+/* Animation keyframes */
+
+@keyframes fade-in {
+  0% {
+    opacity: 0;
+    transform: scaleY(0);
+    display: none;
+  }
+
+  100% {
+    opacity: 1;
+    transform: scaleY(1);
+    display: block;
+  }
+}
+
+@keyframes fade-out {
+  0% {
+    opacity: 1;
+    transform: scaleY(1);
+    display: block;
+  }
+
+  100% {
+    opacity: 0;
+    transform: scaleY(0);
+    display: none;
+  }
+}
+
+body,
+button {
+  font-family: system-ui;
+}
+
+/* Transition the :backdrop when the dialog modal is promoted to the top layer */
+::backdrop {
+  background-color: rgba(0, 0, 0, 0.1);
+  transition:
+    background-color 0.5s,
+    display 0.5s allow-discrete,
+    overlay 0.5s allow-discrete;
+}
+
+@starting-style {
+  ::backdrop {
+    background-color: rgba(0, 0, 0, 0);
+  }
+}
+```
+
+Note the keyframes defined to animate between the closed and open states, which are then applied to control classes. This includes animating `display` to make sure the actual visible animation effects remain visible for the whole duration. Note also that the animation example includes the same [`::backdrop`](/en-US/docs/Web/CSS/::backdrop) transition as the transition demo, to fade the backdrop in. This didn't seem possible to reproduce with a keyframe animation.
+
+Finally, the JavaScript serves to wire up the buttons to event handlers that show and close the `<dialog>`, while also adding and removing the control classes as required to apply the entry and exit animations. In addition, note how {{domxref("setTimeout()")}} is used to defer closing the `<dialog>` until the exit animation is finished.
+
+```js
+const dialogElem = document.getElementById("dialog");
+const showBtn = document.querySelector(".show");
+const closeBtn = document.querySelector(".close");
+
+showBtn.addEventListener("click", () => {
+  dialogElem.classList.remove("fade-out");
+  dialogElem.classList.add("fade-in");
+  dialogElem.showModal();
+});
+
+closeBtn.addEventListener("click", () => {
+  dialogElem.classList.remove("fade-in");
+  dialogElem.classList.add("fade-out");
+  setTimeout(() => {
+    dialogElem.close();
+  }, 500);
+});
+```
+
+The code renders as follows:
+
+{{ EmbedLiveSample("dialog keyframe animations", "100%", "200") }}
+
 ## Technical summary
 
 <table class="properties">

From 8fdd02c78c809c24a45d94fbb5dfa6e2a93999c0 Mon Sep 17 00:00:00 2001
From: Chris Mills <chrisdavidmills@gmail.com>
Date: Wed, 27 Sep 2023 18:21:03 +0100
Subject: [PATCH 3/4] Improving popover transition examples based on
 josepharhar feedback

---
 .../en-us/web/api/popover_api/using/index.md  | 62 +++++++++----------
 files/en-us/web/css/@starting-style/index.md  | 25 ++++++++
 files/en-us/web/css/overlay/index.md          | 25 ++++++++
 .../web/css/transition-behavior/index.md      | 25 ++++++++
 files/en-us/web/html/element/dialog/index.md  | 46 ++++++--------
 5 files changed, 123 insertions(+), 60 deletions(-)

diff --git a/files/en-us/web/api/popover_api/using/index.md b/files/en-us/web/api/popover_api/using/index.md
index c7ba84f56ae52dd..295649603e15eea 100644
--- a/files/en-us/web/api/popover_api/using/index.md
+++ b/files/en-us/web/api/popover_api/using/index.md
@@ -335,19 +335,7 @@ html {
   font-family: Arial, Helvetica, sans-serif;
 }
 
-::backdrop {
-  background-color: rgba(0, 0, 0, 0.1);
-  transition:
-    background-color 0.5s,
-    display 0.5s allow-discrete,
-    overlay 0.5s allow-discrete;
-}
-
-@starting-style {
-  ::backdrop {
-    background-color: rgba(0, 0, 0, 0);
-  }
-}
+/* Transition for the popover itself */
 
 [popover]:popover-open {
   opacity: 1;
@@ -366,17 +354,40 @@ html {
     display 0.7s allow-discrete;
 }
 
-/* Needs to be included after the previous [popover]:popover-open rule
-   to take effect, as the specificity is the same */
+/* Needs to be after the previous [popover]:popover-open rule to take effect,
+    as the specificity is the same */
 @starting-style {
   [popover]:popover-open {
     opacity: 0;
     transform: scaleX(0);
   }
 }
+
+/* Transition for the popover's backdrop */
+
+[popover]::backdrop {
+  background-color: rgba(0, 0, 0, 0);
+  transition:
+    display 0.7s allow-discrete,
+    overlay 0.7s allow-discrete,
+    background-color 0.7s;
+}
+
+[popover]:popover-open::backdrop {
+  background-color: rgba(0, 0, 0, 0.25);
+}
+
+/* This starting-style rule cannot be nested inside the above selector
+because the nesting selector cannot represent pseudo-elements. */
+
+@starting-style {
+  [popover]:popover-open::backdrop {
+    background-color: rgba(0, 0, 0, 0);
+  }
+}
 ```
 
-The two properties we want to show animations for are [`opacity`](/en-US/docs/Web/CSS/opacity) and [`transform`](/en-US/docs/Web/CSS/transform) (specifically, a horizontally scaling transform): we want the popover to fade in and out, as well as growing/shrinking horizontally.To achieve this, we have set a starting state for these properties on the default hidden state of the popover element (selected via `[popover]`), and an end state on the open state of the popover (selected via the [`:popover-open`](/en-US/docs/Web/CSS/:popover-open) pseudo-class). We then set a [`transition`](/en-US/docs/Web/CSS/transition) property to animate between the two.
+The two popover properties we want to show animations for are [`opacity`](/en-US/docs/Web/CSS/opacity) and [`transform`](/en-US/docs/Web/CSS/transform) — specifically, a horizontally scaling transform. We want the popover to fade in and out, as well as growing/shrinking horizontally. To achieve this, we have set a starting state for these properties on the default hidden state of the popover element (selected via `[popover]`), and an end state on the open state of the popover (selected via the [`:popover-open`](/en-US/docs/Web/CSS/:popover-open) pseudo-class). We then set a [`transition`](/en-US/docs/Web/CSS/transition) property to animate between the two.
 
 And as discussed earlier, we have:
 
@@ -385,7 +396,7 @@ And as discussed earlier, we have:
 - Added `overlay` to the list of transitioned elements to make sure that the removal of the element from the top layer is deferred until the animation has been completed. This doesn't make a huge difference for simple animations such as this one, but in more complex cases not doing this can result in the element being removed from the overlay too quickly, meaning the animation is not smooth or effective.
 - Set `allow-discrete` on both the above transitions to enable discrete transitions.
 
-You'll note that we have also done something similar for the [`::backdrop`](/en-US/docs/Web/CSS/::backdrop) that appears behind the popover when it opens, to provide a nice darkening animation.
+You'll note that we've also included a transition on the [`::backdrop`](/en-US/docs/Web/CSS/::backdrop) that appears behind the popover when it opens, to provide a nice darkening animation. `[popover]:popover-open::backdrop` is needed to select the backdrop when the popover is open.
 
 The code renders as follows:
 
@@ -413,21 +424,6 @@ html {
   font-family: Arial, Helvetica, sans-serif;
 }
 
-/* Transition the :backdrop when the popover is promoted to the top layer */
-::backdrop {
-  background-color: rgba(0, 0, 0, 0.1);
-  transition:
-    background-color 0.5s,
-    display 0.5s allow-discrete,
-    overlay 0.5s allow-discrete;
-}
-
-@starting-style {
-  ::backdrop {
-    background-color: rgba(0, 0, 0, 0);
-  }
-}
-
 [popover] {
   font-size: 1.2rem;
   padding: 10px;
@@ -474,7 +470,7 @@ html {
 }
 ```
 
-We have defined keyframes that specify the desired entry and exit animations, and assigned those to CSS classes. Note also that the animation example includes the same [`::backdrop`](/en-US/docs/Web/CSS/::backdrop) transition as the transition demo, to fade the backdrop in. This didn't seem possible to reproduce with a keyframe animation.
+We have defined keyframes that specify the desired entry and exit animations, and assigned those to CSS classes. This example doesn't animate the backdrop like the transitions example above did, as that didn't seem possible to reproduce with a keyframe animation in our experiments.
 
 We then use some rudimentary JavaScript to apply those classes to the popover as it is shown and hidden, triggering the animations at the right times. As mentioned earlier, we have used `setTimeout()` to defer the hiding of the popover until the animations have finished.
 
diff --git a/files/en-us/web/css/@starting-style/index.md b/files/en-us/web/css/@starting-style/index.md
index d7ff28b1c9e88f8..4ba85e730fed78f 100644
--- a/files/en-us/web/css/@starting-style/index.md
+++ b/files/en-us/web/css/@starting-style/index.md
@@ -118,6 +118,29 @@ html {
     transform: scaleX(0);
   }
 }
+
+/* Transition for the popover's backdrop */
+
+[popover]::backdrop {
+  background-color: rgba(0, 0, 0, 0);
+  transition:
+    display 0.7s allow-discrete,
+    overlay 0.7s allow-discrete,
+    background-color 0.7s;
+}
+
+[popover]:popover-open::backdrop {
+  background-color: rgba(0, 0, 0, 0.25);
+}
+
+/* This starting-style rule cannot be nested inside the above selector
+because the nesting selector cannot represent pseudo-elements. */
+
+@starting-style {
+  [popover]:popover-open::backdrop {
+    background-color: rgba(0, 0, 0, 0);
+  }
+}
 ```
 
 The two properties we want to animate are [`opacity`](/en-US/docs/Web/CSS/opacity) and [`transform`](/en-US/docs/Web/CSS/transform) (specifically, a horizontally scaling transform): we want the popover to fade in and out, as well as growing/shrinking horizontally. To achieve this, we have set a starting state for these properties on the default hidden state of the popover element (selected via `[popover]`), and an end state on the open state of the popover (selected via the [`:popover-open`](/en-US/docs/Web/CSS/:popover-open) pseudo-class).
@@ -129,6 +152,8 @@ However, because the animated element is being promoted to the [top layer](/en-U
 - `display` is added to the list of transitioned elements so that the animated element is visible (set to `display: block`) throughout both the entry and exit animation. Without this, the exit animation would not be visible; in effect, the popover would just disappear. Note that the [`transition-behavior: allow-discrete`](/en-US/docs/Web/CSS/transition-behavior) value is also set in the shorthand so that it will animate.
 - [`overlay`](/en-US/docs/Web/CSS/overlay) is added to the list of transitioned elements to make sure that the removal of the element from the top layer is deferred until the animation has been completed. This doesn't make a huge difference for simple animations such as this one, but in more complex cases not doing this can result in the element being removed from the overlay too quickly, meaning the animation is not smooth or effective. Again, `transition-behavior: allow-discrete` is required in this case for the animation to occur.
 
+You'll note that we've also included a transition on the [`::backdrop`](/en-US/docs/Web/CSS/::backdrop) that appears behind the popover when it opens, to provide a nice darkening animation. `[popover]:popover-open::backdrop` is needed to select the backdrop when the popover is open.
+
 The code renders as follows:
 
 {{ EmbedLiveSample("Animating a popover", "100%", "200") }}
diff --git a/files/en-us/web/css/overlay/index.md b/files/en-us/web/css/overlay/index.md
index 4626d46d731e8d9..8500733419cfbae 100644
--- a/files/en-us/web/css/overlay/index.md
+++ b/files/en-us/web/css/overlay/index.md
@@ -83,6 +83,29 @@ html {
     transform: scaleX(0);
   }
 }
+
+/* Transition for the popover's backdrop */
+
+[popover]::backdrop {
+  background-color: rgba(0, 0, 0, 0);
+  transition:
+    display 0.7s allow-discrete,
+    overlay 0.7s allow-discrete,
+    background-color 0.7s;
+}
+
+[popover]:popover-open::backdrop {
+  background-color: rgba(0, 0, 0, 0.25);
+}
+
+/* This starting-style rule cannot be nested inside the above selector
+because the nesting selector cannot represent pseudo-elements. */
+
+@starting-style {
+  [popover]:popover-open::backdrop {
+    background-color: rgba(0, 0, 0, 0);
+  }
+}
 ```
 
 The two properties we want to animate are [`opacity`](/en-US/docs/Web/CSS/opacity) and [`transform`](/en-US/docs/Web/CSS/transform) (specifically, a horizontally scaling transform): we want the popover to fade in and out, as well as growing/shrinking horizontally. To achieve this, we have set a starting state for these properties on the default hidden state of the popover element (selected via `[popover]`), and an end state on the open state of the popover (selected via the [`:popover-open`](/en-US/docs/Web/CSS/:popover-open) pseudo-class). We then set a [`transition`](/en-US/docs/Web/CSS/transition) property to animate between the two.
@@ -93,6 +116,8 @@ However, because the animated element is being promoted to the [top layer](/en-U
 - `display` is added to the list of transitioned elements so that the animated element is visible (set to `display: block`) throughout both the entry and exit animation. Without this, the exit animation would not be visible; in effect, the popover would just disappear. Note that the [`transition-behavior: allow-discrete`](/en-US/docs/Web/CSS/transition-behavior) value is also set in the shorthand so that it will animate.
 - `overlay` is added to the list of transitioned elements to make sure that the removal of the element from the top layer is deferred until the animation has been completed. This doesn't make a huge difference for simple animations such as this one, but in more complex cases not doing this can result in the element being removed from the overlay too quickly, meaning the animation is not smooth or effective. Again, `transition-behavior: allow-discrete` is required in this case for the animation to occur.
 
+You'll note that we've also included a transition on the [`::backdrop`](/en-US/docs/Web/CSS/::backdrop) that appears behind the popover when it opens, to provide a nice darkening animation. `[popover]:popover-open::backdrop` is needed to select the backdrop when the popover is open.
+
 The code renders as follows:
 
 {{ EmbedLiveSample("Animating a popover", "100%", "200") }}
diff --git a/files/en-us/web/css/transition-behavior/index.md b/files/en-us/web/css/transition-behavior/index.md
index e2d47a0e034ae73..73e333ed582f26a 100644
--- a/files/en-us/web/css/transition-behavior/index.md
+++ b/files/en-us/web/css/transition-behavior/index.md
@@ -105,6 +105,29 @@ html {
     transform: scaleX(0);
   }
 }
+
+/* Transition for the popover's backdrop */
+
+[popover]::backdrop {
+  background-color: rgba(0, 0, 0, 0);
+  transition:
+    display 0.7s allow-discrete,
+    overlay 0.7s allow-discrete,
+    background-color 0.7s;
+}
+
+[popover]:popover-open::backdrop {
+  background-color: rgba(0, 0, 0, 0.25);
+}
+
+/* This starting-style rule cannot be nested inside the above selector
+because the nesting selector cannot represent pseudo-elements. */
+
+@starting-style {
+  [popover]:popover-open::backdrop {
+    background-color: rgba(0, 0, 0, 0);
+  }
+}
 ```
 
 The two properties we want to animate are [`opacity`](/en-US/docs/Web/CSS/opacity) and [`transform`](/en-US/docs/Web/CSS/transform) (specifically, a horizontally scaling transform): we want the popover to fade in and out, as well as growing/shrinking horizontally. To achieve this, we have set a starting state for these properties on the default hidden state of the popover element (selected via `[popover]`), and an end state on the open state of the popover (selected via the [`:popover-open`](/en-US/docs/Web/CSS/:popover-open) pseudo-class). We then set a [`transition`](/en-US/docs/Web/CSS/transition) property to animate between the two.
@@ -117,6 +140,8 @@ However, because the animated element is being promoted to the [top layer](/en-U
 
 In the transitions list, `transition-behavior: allow-discrete` is set in the shorthand for both `display` and `overlay` so that they will animate.
 
+You'll note that we've also included a transition on the [`::backdrop`](/en-US/docs/Web/CSS/::backdrop) that appears behind the popover when it opens, to provide a nice darkening animation. `[popover]:popover-open::backdrop` is needed to select the backdrop when the popover is open.
+
 The code renders as follows:
 
 {{ EmbedLiveSample("Animating a popover", "100%", "200") }}
diff --git a/files/en-us/web/html/element/dialog/index.md b/files/en-us/web/html/element/dialog/index.md
index 44a62a166a4e00e..d7bd9c85b83ac32 100644
--- a/files/en-us/web/html/element/dialog/index.md
+++ b/files/en-us/web/html/element/dialog/index.md
@@ -166,13 +166,13 @@ The HTML contains a `<dialog>` element, plus a button to show the dialog. Additi
 The CSS is as follows:
 
 ```css
-/* Open state of the dialog */
+/*   Open state of the dialog */
 dialog[open] {
   opacity: 1;
   transform: scaleY(1);
 }
 
-/* Closed state of the dialog */
+/*   Closed state of the dialog   */
 dialog {
   transition:
     opacity 0.5s ease-out,
@@ -183,9 +183,9 @@ dialog {
   transform: scaleY(0);
 }
 
-/* Before-open state  */
+/*   Before-open state  */
 /* Needs to be after the previous dialog[open] rule to take effect,
-   as the specificity is the same */
+    as the specificity is the same */
 @starting-style {
   dialog[open] {
     opacity: 0;
@@ -194,16 +194,23 @@ dialog {
 }
 
 /* Transition the :backdrop when the dialog modal is promoted to the top layer */
-::backdrop {
-  background-color: rgba(0, 0, 0, 0.1);
+dialog::backdrop {
+  background-color: rgba(0, 0, 0, 0);
   transition:
-    background-color 0.5s,
-    display 0.5s allow-discrete,
-    overlay 0.5s allow-discrete;
+    display 0.7s allow-discrete,
+    overlay 0.7s allow-discrete,
+    background-color 0.7s;
 }
 
+dialog[open]::backdrop {
+  background-color: rgba(0, 0, 0, 0.25);
+}
+
+/* This starting-style rule cannot be nested inside the above selector
+because the nesting selector cannot represent pseudo-elements. */
+
 @starting-style {
-  ::backdrop {
+  dialog[open]::backdrop {
     background-color: rgba(0, 0, 0, 0);
   }
 }
@@ -214,7 +221,7 @@ button {
 }
 ```
 
-Note the `@starting-style` block used to define the transition starting styles, and the `display` and `overlay` properties included in the transition list, each with `allow-discrete` set on them. Note that we've also included similar CSS to transition the [`::backdrop`](/en-US/docs/Web/CSS/::backdrop) that appears behind the `<dialog>` when it opens, to provide a nice darkening animation.
+Note the `@starting-style` block used to define the transition starting styles, and the `display` and `overlay` properties included in the transition list, each with `allow-discrete` set on them. Note that we've also included similar CSS to transition the [`::backdrop`](/en-US/docs/Web/CSS/::backdrop) that appears behind the `<dialog>` when it opens, to provide a nice darkening animation. `dialog[open]::backdrop` is required to select the backdrop when the dialog is open.
 
 The JavaScript serves to wire up the buttons to event handlers that show and close the `<dialog>`:
 
@@ -302,24 +309,9 @@ body,
 button {
   font-family: system-ui;
 }
-
-/* Transition the :backdrop when the dialog modal is promoted to the top layer */
-::backdrop {
-  background-color: rgba(0, 0, 0, 0.1);
-  transition:
-    background-color 0.5s,
-    display 0.5s allow-discrete,
-    overlay 0.5s allow-discrete;
-}
-
-@starting-style {
-  ::backdrop {
-    background-color: rgba(0, 0, 0, 0);
-  }
-}
 ```
 
-Note the keyframes defined to animate between the closed and open states, which are then applied to control classes. This includes animating `display` to make sure the actual visible animation effects remain visible for the whole duration. Note also that the animation example includes the same [`::backdrop`](/en-US/docs/Web/CSS/::backdrop) transition as the transition demo, to fade the backdrop in. This didn't seem possible to reproduce with a keyframe animation.
+Note the keyframes defined to animate between the closed and open states, which are then applied to control classes. This includes animating `display` to make sure the actual visible animation effects remain visible for the whole duration. This example does not animate the backdrop like the above transition demo does; this didn't seem possible to reproduce with a keyframe animation in our experiments.
 
 Finally, the JavaScript serves to wire up the buttons to event handlers that show and close the `<dialog>`, while also adding and removing the control classes as required to apply the entry and exit animations. In addition, note how {{domxref("setTimeout()")}} is used to defer closing the `<dialog>` until the exit animation is finished.
 

From 31142db3fd68e7d6ad76fb6443d2134bac0d0980 Mon Sep 17 00:00:00 2001
From: Chris Mills <chrisdavidmills@gmail.com>
Date: Tue, 10 Oct 2023 13:05:34 +0100
Subject: [PATCH 4/4] improve popover keyframe example with beforetoggle

---
 files/en-us/web/api/popover_api/using/index.md | 18 ++++++++----------
 files/en-us/web/html/element/dialog/index.md   |  8 +++-----
 2 files changed, 11 insertions(+), 15 deletions(-)

diff --git a/files/en-us/web/api/popover_api/using/index.md b/files/en-us/web/api/popover_api/using/index.md
index 295649603e15eea..e7de99a2b0c60cb 100644
--- a/files/en-us/web/api/popover_api/using/index.md
+++ b/files/en-us/web/api/popover_api/using/index.md
@@ -303,16 +303,14 @@ See our [Popover blur background example](https://mdn.github.io/dom-examples/pop
 
 ## Animating popovers
 
-For popovers to be animated, several different features are required.
-
-First of all, popovers are set to `display: none;` when hidden and `display: block;` when shown, as well as being removed from / added to the {{glossary("top layer")}}. Therefore, `display` needs to be animatable. This is now the case; [supporting browsers](/en-US/docs/Web/CSS/display#browser_compatibility) animate `display` with a variation on the [discrete animation type](/en-US/docs/Web/CSS/CSS_animated_properties#discrete). Specifically, the browser will flip between `none` and another value of `display` so that the animated content is shown for `100%` of the animation duration. So for example:
+Popovers are set to `display: none;` when hidden and `display: block;` when shown, as well as being removed from / added to the {{glossary("top layer")}}. Therefore, for popovers to be animated `display` needs to be animatable. This is now the case; [supporting browsers](/en-US/docs/Web/CSS/display#browser_compatibility) animate `display` with a variation on the [discrete animation type](/en-US/docs/Web/CSS/CSS_animated_properties#discrete). Specifically, the browser will flip between `none` and another value of `display` so that the animated content is shown for `100%` of the animation duration. So for example:
 
 - When animating between `display` `none` and `block`, the value will flip to `block` at `0%` of the animation duration so it is visible throughout.
 - When animating between `display` `block` and `none`, the value will flip to `none` at `100%` of the animation duration so it is visible throughout.
 
 ### Transitioning a popover
 
-When animating popovers with transitions, these additional features are needed:
+When animating popovers with transitions, the following are required:
 
 - [`@starting-style`](/en-US/docs/Web/CSS/@starting-style) is used to provide a set of starting values for properties set on the popover that you want to transition from when it is shown. This is needed because, by default, [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions) are not triggered on elements' first style updates, or when the `display` type changes from `none` to another type, to avoid unexpected behavior.
 - [`display`](/en-US/docs/Web/CSS/display) needs to be added to the transitions list so that the popover will remain as `display: block` for the duration of the animation, allowing the other animations to be seen.
@@ -408,12 +406,12 @@ When animating a popover with [CSS animations](/en-US/docs/Web/CSS/CSS_animation
 
 - You don't provide a starting state inside a `@starting-style` block; instead, you need to provide the starting `display` value in an explicit starting keyframe (for example using `0%` or `from`).
 - You don't need to enable discrete transitions; there is no equivalent to `allow-discrete` inside keyframes.
-- You can't set `overlay` inside keyframes either. The best solution we found at this time to defer removal from the top layer was to use JavaScript — animating the popover and then using {{domxref("setTimeout()")}} to defer removal of the popover until after the animation is finished.
+- You can't set `overlay` inside keyframes either. The best solution we found at this time to defer removal from the top layer was to use JavaScript — add/remove classes to animate the popover as required and then use {{domxref("setTimeout()")}} to defer hiding the popover until after the animation is finished.
 
-Let's look at an example. The HTML is contains a {{htmlelement("div")}} element declared as a popover, and a {{htmlelement("button")}} element designated as the popover's toggle control:
+Let's look at an example. The HTML contains a {{htmlelement("div")}} element declared as a popover, and a {{htmlelement("button")}} element designated as the popover's toggle control:
 
 ```html
-<button id="toggle-button">Toggle the popover</button>
+<button id="toggle-button" popovertarget="mypopover">Toggle the popover</button>
 <div popover="manual" id="mypopover">I'm a Popover! I should animate.</div>
 ```
 
@@ -470,15 +468,15 @@ html {
 }
 ```
 
-We have defined keyframes that specify the desired entry and exit animations, and assigned those to CSS classes. This example doesn't animate the backdrop like the transitions example above did, as that didn't seem possible to reproduce with a keyframe animation in our experiments.
+We have defined keyframes that specify the desired entry and exit animations, and assigned those to CSS classes. This example doesn't animate the backdrop like the transitions example above does — that wasn't possible to reproduce with a keyframe animation at the time of writing.
 
-We then use some rudimentary JavaScript to apply those classes to the popover as it is shown and hidden, triggering the animations at the right times. As mentioned earlier, we have used `setTimeout()` to defer the hiding of the popover until the animations have finished.
+We then use some rudimentary JavaScript to apply those classes to the popover as it is toggled between shown and hidden (via the handy {{domxref("HTMLElement.beforetoggle_event", "beforetoggle")}} event), triggering the animations at the right times. As mentioned earlier, we have used `setTimeout()` to defer hiding the popover until the animations have finished.
 
 ```js
 const popover = document.getElementById("mypopover");
 const toggleBtn = document.getElementById("toggle-button");
 
-toggleBtn.addEventListener("click", () => {
+popover.addEventListener("beforetoggle", () => {
   if (!popover.matches(":popover-open")) {
     popover.classList.remove("fade-out");
     popover.classList.add("fade-in");
diff --git a/files/en-us/web/html/element/dialog/index.md b/files/en-us/web/html/element/dialog/index.md
index d7bd9c85b83ac32..13cbebd4f9f0b1c 100644
--- a/files/en-us/web/html/element/dialog/index.md
+++ b/files/en-us/web/html/element/dialog/index.md
@@ -134,16 +134,14 @@ It is important to provide a closing mechanism within every `dialog` element. Th
 
 ### Animating dialogs
 
-For `<dialog>` elements to be animated, several different features are required.
-
-First of all, `<dialog>`s are set to `display: none;` when hidden and `display: block;` when shown, as well as being removed from / added to the {{glossary("top layer")}}. Therefore, `display` needs to be animatable. This is now the case; [supporting browsers](/en-US/docs/Web/CSS/display#browser_compatibility) animate `display` with a variation on the [discrete animation type](/en-US/docs/Web/CSS/CSS_animated_properties#discrete). Specifically, the browser will flip between `none` and another value of `display` so that the animated content is shown for `100%` of the animation duration. So for example:
+`<dialog>`s are set to `display: none;` when hidden and `display: block;` when shown, as well as being removed from / added to the {{glossary("top layer")}}. Therefore, for `<dialog>` elements to be animated `display` needs to be animatable. This is now the case; [supporting browsers](/en-US/docs/Web/CSS/display#browser_compatibility) animate `display` with a variation on the [discrete animation type](/en-US/docs/Web/CSS/CSS_animated_properties#discrete). Specifically, the browser will flip between `none` and another value of `display` so that the animated content is shown for `100%` of the animation duration. So for example:
 
 - When animating between `display` `none` and `block`, the value will flip to `block` at `0%` of the animation duration so it is visible throughout.
 - When animating between `display` `block` and `none`, the value will flip to `none` at `100%` of the animation duration so it is visible throughout.
 
 #### Transitioning dialog elements
 
-When animating `<dialog>`s with [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions), these additional features are needed:
+When animating `<dialog>`s with [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions), the following are required:
 
 - [`@starting-style`](/en-US/docs/Web/CSS/@starting-style) is used to provide a set of starting values for properties set on the `<dialog>` that you want to transition from when it is shown. This is needed because, by default, [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions) are not triggered on elements' first style updates, or when the `display` type changes from `none` to another type, to avoid unexpected behavior.
 - [`display`](/en-US/docs/Web/CSS/display) needs to be added to the transitions list so that the `<dialog>` will remain as `display: block` for the duration of the animation, allowing the other animations to be seen.
@@ -311,7 +309,7 @@ button {
 }
 ```
 
-Note the keyframes defined to animate between the closed and open states, which are then applied to control classes. This includes animating `display` to make sure the actual visible animation effects remain visible for the whole duration. This example does not animate the backdrop like the above transition demo does; this didn't seem possible to reproduce with a keyframe animation in our experiments.
+Note the keyframes defined to animate between the closed and open states, which are then applied to control classes. This includes animating `display` to make sure the actual visible animation effects remain visible for the whole duration. This example doesn't animate the backdrop like the transitions example above does — that wasn't possible to reproduce with a keyframe animation at the time of writing.
 
 Finally, the JavaScript serves to wire up the buttons to event handlers that show and close the `<dialog>`, while also adding and removing the control classes as required to apply the entry and exit animations. In addition, note how {{domxref("setTimeout()")}} is used to defer closing the `<dialog>` until the exit animation is finished.