From 01bb3352b0a3b451d6b83c084cca2070928cd542 Mon Sep 17 00:00:00 2001
From: Dipika Bhattacharya <dipika@foss-community.org>
Date: Tue, 26 Sep 2023 20:58:54 -0400
Subject: [PATCH] fix(css): Clarify text and example for complex selectors with
 general sibling combinator (~) (#29093)

* clarifies text and adds examples

* fixes review comments

* adds link to complex selectors

* fixes review comments

* fixes example text
---
 .../css/general_sibling_combinator/index.md   | 66 ++++++++++++++-----
 1 file changed, 51 insertions(+), 15 deletions(-)

diff --git a/files/en-us/web/css/general_sibling_combinator/index.md b/files/en-us/web/css/general_sibling_combinator/index.md
index d07bf8b5cad9ef1..068cdf8d557fddc 100644
--- a/files/en-us/web/css/general_sibling_combinator/index.md
+++ b/files/en-us/web/css/general_sibling_combinator/index.md
@@ -7,11 +7,11 @@ browser-compat: css.selectors.general_sibling
 
 {{CSSRef("Selectors")}}
 
-The **general sibling combinator** (`~`) separates two selectors and matches _all iterations_ of the second element, that are following the first element (though not necessarily immediately), and are children of the same parent {{Glossary("element")}}.
+The **general sibling combinator** (`~`) separates two selectors and matches _all instances_ of the second element that follow the first element (not necessarily immediately) and share the same parent element.
+
+In the following example, the general sibling combinator (`~`) helps to select and style paragraphs that are both siblings of an image and appear after any image.
 
 ```css
-/* Paragraphs that are siblings of and
-   subsequent to any image */
 img ~ p {
   color: red;
 }
@@ -26,15 +26,9 @@ former_element ~ target_element { style properties }
 
 ## Examples
 
-### CSS
-
-```css
-p ~ span {
-  color: red;
-}
-```
+### Using the combinator with simple selectors
 
-### HTML
+This example shows the use of the `~` combinator when both the selectors are simple selectors (`p` and `span`).
 
 ```html
 <article>
@@ -43,7 +37,7 @@ p ~ span {
   <code>Here is some code.</code>
   <span>
     This span is red because it appears after the paragraph, even though there
-    are other nodes in between
+    are other nodes in between.
   </span>
   <p>Whatever it may be, keep smiling.</p>
   <h1>Dream big</h1>
@@ -53,13 +47,55 @@ p ~ span {
   </span>
 </article>
 <span>
-  This span is not red because it doesn't share a parent with a paragraph
+  This span is not red because it doesn't share a parent with a paragraph.
 </span>
 ```
 
-### Result
+```css
+p ~ span {
+  color: red;
+}
+```
+
+{{EmbedLiveSample("Using the combinator with simple selectors", "auto", 300)}}
+
+### Using the combinator with complex selectors
+
+This example contains two [complex selectors](/en-US/docs/Web/CSS/CSS_selectors/Selector_structure#complex_selector), both using the general sibling combinator: `.foo p ~ span` and `.foo p ~ .foo span`.
+
+- The first complex selector, `.foo p ~ span`, matches all spans that come after a paragraph _if_ the span and paragraph share the same parent **and** that parent or an ancestor of that parent has the class `.foo`.
+- The second complex selector, `.foo p ~ .foo span`, matches all spans that are a descendant of the element with class `.foo` _if_ that element is a sibling of the previously mentioned paragraph.
+
+The example below shows that the target element in the complex selector must share the same parent as the initial element in the complex selector.
+
+```html
+<h1>Dream big</h1>
+<span>And yet again this is a red span!</span>
+<div class="foo">
+  <p>Here is another paragraph.</p>
+  <span>A blue span</span>
+  <div class="foo">
+    <span>A green span</span>
+  </div>
+</div>
+```
+
+```css
+.foo p ~ span {
+  color: blue;
+}
+
+.foo p ~ .foo span {
+  color: green;
+}
+```
+
+{{EmbedLiveSample("Using the combinator with complex selectors", "auto", 200)}}
+
+In the above HTML, the two siblings of `.foo p` are `span` and `.foo`. The green `span` is a descendant of the `.foo` class, which is a sibling of `p`.
 
-{{EmbedLiveSample("Examples", "auto", 300)}}
+- When the target selector is `span`, the `span` element that is a sibling of `p` is selected. The `p` element is a descendant of `.foo`, so are its `span` siblings.
+- In `.foo p ~ .foo span`, the target selector is `span` that is a descendant of `.foo`. In this case, the `span` element that's a descendent of `.foo` is selected if that `.foo` is a sibling of `p`; essentially, both are nested in an ancestor of `.foo`.
 
 ## Specifications