Add example descriptions

files/en-us/web/css/_doublecolon_details-content/index.md

@@ -21,6 +21,8 @@ selector::details-content
 
 ### Basic example
 
+In this example the `::details-content` pseudo-element is used to set a {{cssxref("background-color")}} on the content of the {{HTMLElement("details")}} element.
+
 #### HTML
 
 ```html
@@ -44,6 +46,11 @@ details::details-content {
 
 ### Transition example
 
+In this example the `::details-content` pseudo-element is used to set a {{cssxref("transition")}} on the content of the {{HTMLElement("details")}} element so that it smoothly fades into view when expanded, and fades out again when collapsed. To achieve this, two separate transitions are specified inside the `transition` shorthand property:
+
+- The {{cssxref("opacity")}} property is given a basic transition over `600ms` to create the fade-in/fade-out effect.
+- The {{cssxref("content-visibility")}} property (which is toggled between `hidden` and `visible` when the `<details>` content is expanded/collapsed) is also given a basic `600ms` transition, but with the {{cssxref("transition-behavior")}} value `allow-discrete` specified. This opts the browser into having a transition started on `content-visibility`, the animation behavior of which is [discrete](/en-US/docs/Web/CSS/CSS_animated_properties#discrete). The effect is that the content is visible for the entire duration of the transition, allowing other transitions to be seen. If this transition was not included, the content would immediately disappear when the `<details>` content was collapsed — you wouldn't see the smooth fade-out.
+
 #### HTML
 
 ```html
@@ -59,8 +66,8 @@ details::details-content {
 details::details-content {
   opacity: 0;
   transition:
-    content-visibility 300ms allow-discrete,
-    opacity 300ms;
+    opacity 600ms,
+    content-visibility 600ms allow-discrete;
 }
 
 details[open]::details-content {