From 74f44f289e31e41ef5fcf5a96e28188a52f6e0d4 Mon Sep 17 00:00:00 2001
From: James Stuckey Weber <james@oddbird.net>
Date: Sun, 29 Sep 2024 20:35:04 -0400
Subject: [PATCH 1/6] Add placeholder, placeholder-shown, selection, and text
 decoration in selection

---
 features/placeholder-shown.yml              | 11 ++++++
 features/placeholder-shown.yml.dist         | 42 +++++++++++++++++++++
 features/placeholder.yml                    |  7 ++++
 features/placeholder.yml.dist               | 17 +++++++++
 features/selection.yml                      |  7 ++++
 features/selection.yml.dist                 | 14 +++++++
 features/text-decoration-selection.yml      |  6 +++
 features/text-decoration-selection.yml.dist | 11 ++++++
 8 files changed, 115 insertions(+)
 create mode 100644 features/placeholder-shown.yml
 create mode 100644 features/placeholder-shown.yml.dist
 create mode 100644 features/placeholder.yml
 create mode 100644 features/placeholder.yml.dist
 create mode 100644 features/selection.yml
 create mode 100644 features/selection.yml.dist
 create mode 100644 features/text-decoration-selection.yml
 create mode 100644 features/text-decoration-selection.yml.dist

diff --git a/features/placeholder-shown.yml b/features/placeholder-shown.yml
new file mode 100644
index 00000000000..622bb373669
--- /dev/null
+++ b/features/placeholder-shown.yml
@@ -0,0 +1,11 @@
+name: :placeholder-shown
+description: The `:placeholder-shown` CSS pseudo-element sets the styles on `<input>` and `<textarea>` elements when no value is set and placeholder text is shown.
+spec: https://drafts.csswg.org/selectors-4/#placeholder
+caniuse: css-placeholder-shown
+group: selectors
+# Compute from entry to match caniuse
+status:
+  compute_from: css.selectors.placeholder-shown
+compat_features:
+  - css.selectors.placeholder-shown
+  - css.selectors.placeholder-shown.non_text_types
diff --git a/features/placeholder-shown.yml.dist b/features/placeholder-shown.yml.dist
new file mode 100644
index 00000000000..2652c975683
--- /dev/null
+++ b/features/placeholder-shown.yml.dist
@@ -0,0 +1,42 @@
+# Generated from: placeholder-shown.yml
+# Do not edit this file by hand. Edit the source file instead!
+
+status:
+  baseline: high
+  baseline_low_date: 2020-01-15
+  baseline_high_date: 2022-07-15
+  support:
+    chrome: "47"
+    chrome_android: "47"
+    edge: "79"
+    firefox: "51"
+    firefox_android: "51"
+    safari: "9"
+    safari_ios: "9"
+compat_features:
+  # ⬇️ Same status as overall feature ⬇️
+  # baseline: high
+  # baseline_low_date: 2020-01-15
+  # baseline_high_date: 2022-07-15
+  # support:
+  #   chrome: "47"
+  #   chrome_android: "47"
+  #   edge: "79"
+  #   firefox: "51"
+  #   firefox_android: "51"
+  #   safari: "9"
+  #   safari_ios: "9"
+  - css.selectors.placeholder-shown
+
+  # baseline: high
+  # baseline_low_date: 2020-01-15
+  # baseline_high_date: 2022-07-15
+  # support:
+  #   chrome: "47"
+  #   chrome_android: "47"
+  #   edge: "79"
+  #   firefox: "59"
+  #   firefox_android: "59"
+  #   safari: "9"
+  #   safari_ios: "9"
+  - css.selectors.placeholder-shown.non_text_types
diff --git a/features/placeholder.yml b/features/placeholder.yml
new file mode 100644
index 00000000000..ffbd7c9d088
--- /dev/null
+++ b/features/placeholder.yml
@@ -0,0 +1,7 @@
+name: ::placeholder
+description: The `::placeholder` CSS pseudo-element sets the styles on text in `<input>` and `<textarea>` elements when no value is set.
+spec: https://drafts.csswg.org/css-pseudo-4/#placeholder-pseudo
+caniuse: https://caniuse.com/css-placeholder
+group: selectors
+compat_features:
+  - css.selectors.placeholder
diff --git a/features/placeholder.yml.dist b/features/placeholder.yml.dist
new file mode 100644
index 00000000000..a295fc921d2
--- /dev/null
+++ b/features/placeholder.yml.dist
@@ -0,0 +1,17 @@
+# Generated from: placeholder.yml
+# Do not edit this file by hand. Edit the source file instead!
+
+status:
+  baseline: high
+  baseline_low_date: 2020-01-15
+  baseline_high_date: 2022-07-15
+  support:
+    chrome: "57"
+    chrome_android: "57"
+    edge: "79"
+    firefox: "51"
+    firefox_android: "51"
+    safari: "10.1"
+    safari_ios: "10.3"
+compat_features:
+  - css.selectors.placeholder
diff --git a/features/selection.yml b/features/selection.yml
new file mode 100644
index 00000000000..e6aa5ad2dbe
--- /dev/null
+++ b/features/selection.yml
@@ -0,0 +1,7 @@
+name: ::selection
+description: The `::selection` CSS pseudo-element sets styles on the text a user has highlighted.
+spec: https://drafts.csswg.org/css-pseudo-4/#selectordef-selection
+caniuse: css-selection
+group: selectors
+compat_features:
+  - css.selectors.selection
diff --git a/features/selection.yml.dist b/features/selection.yml.dist
new file mode 100644
index 00000000000..62a7a09e7e4
--- /dev/null
+++ b/features/selection.yml.dist
@@ -0,0 +1,14 @@
+# Generated from: selection.yml
+# Do not edit this file by hand. Edit the source file instead!
+
+status:
+  baseline: false
+  support:
+    chrome: "1"
+    chrome_android: "18"
+    edge: "12"
+    firefox: "62"
+    firefox_android: "62"
+    safari: "1.1"
+compat_features:
+  - css.selectors.selection
diff --git a/features/text-decoration-selection.yml b/features/text-decoration-selection.yml
new file mode 100644
index 00000000000..80c9bde4b0e
--- /dev/null
+++ b/features/text-decoration-selection.yml
@@ -0,0 +1,6 @@
+name: text-decoration in ::selection
+description: The `text-decoration` CSS property in a `::selection` rule sets the underline and other text decoration styles on the text a user has highlighted.
+spec: https://drafts.csswg.org/css-pseudo/#highlight-styling
+group: selectors
+compat_features:
+  - css.selectors.selection.text-decoration
diff --git a/features/text-decoration-selection.yml.dist b/features/text-decoration-selection.yml.dist
new file mode 100644
index 00000000000..4ca1d359c02
--- /dev/null
+++ b/features/text-decoration-selection.yml.dist
@@ -0,0 +1,11 @@
+# Generated from: text-decoration-selection.yml
+# Do not edit this file by hand. Edit the source file instead!
+
+status:
+  baseline: false
+  support:
+    chrome: "105"
+    chrome_android: "105"
+    edge: "105"
+compat_features:
+  - css.selectors.selection.text-decoration

From db1b4228cfa8b2deabdb72547633b9bdc3a0b239 Mon Sep 17 00:00:00 2001
From: James Stuckey Weber <james@oddbird.net>
Date: Sun, 29 Sep 2024 20:46:44 -0400
Subject: [PATCH 2/6] Add first-letter and first-line

---
 features/first-letter.yml      | 11 +++++++++
 features/first-letter.yml.dist | 41 ++++++++++++++++++++++++++++++++++
 features/first-line.yml        | 10 +++++++++
 features/first-line.yml.dist   | 35 +++++++++++++++++++++++++++++
 4 files changed, 97 insertions(+)
 create mode 100644 features/first-letter.yml
 create mode 100644 features/first-letter.yml.dist
 create mode 100644 features/first-line.yml
 create mode 100644 features/first-line.yml.dist

diff --git a/features/first-letter.yml b/features/first-letter.yml
new file mode 100644
index 00000000000..1dfff67261e
--- /dev/null
+++ b/features/first-letter.yml
@@ -0,0 +1,11 @@
+name: ::first-letter
+description: The `::first-letter` CSS pseudo-element sets the styles of the first letter in an element.
+spec: https://drafts.csswg.org/css-pseudo-4/#first-letter-pseudo
+group: selectors
+caniuse: css-first-letter
+status:
+  compute_from: css.selectors.first-letter
+compat_features:
+  - css.selectors.first-letter
+  - css.selectors.first-letter.dutch_ij_digraph
+  - css.selectors.first-letter.svg_text_element
diff --git a/features/first-letter.yml.dist b/features/first-letter.yml.dist
new file mode 100644
index 00000000000..441d91a0679
--- /dev/null
+++ b/features/first-letter.yml.dist
@@ -0,0 +1,41 @@
+# Generated from: first-letter.yml
+# Do not edit this file by hand. Edit the source file instead!
+
+status:
+  baseline: high
+  baseline_low_date: 2015-07-29
+  baseline_high_date: 2018-01-29
+  support:
+    chrome: "1"
+    chrome_android: "18"
+    edge: "12"
+    firefox: "1"
+    firefox_android: "4"
+    safari: "1"
+    safari_ios: "1"
+compat_features:
+  # ⬇️ Same status as overall feature ⬇️
+  # baseline: high
+  # baseline_low_date: 2015-07-29
+  # baseline_high_date: 2018-01-29
+  # support:
+  #   chrome: "1"
+  #   chrome_android: "18"
+  #   edge: "12"
+  #   firefox: "1"
+  #   firefox_android: "4"
+  #   safari: "1"
+  #   safari_ios: "1"
+  - css.selectors.first-letter
+
+  # baseline: false
+  # support:
+  #   firefox: "87"
+  #   firefox_android: "87"
+  - css.selectors.first-letter.dutch_ij_digraph
+
+  # baseline: false
+  # support:
+  #   firefox: "124"
+  #   firefox_android: "124"
+  - css.selectors.first-letter.svg_text_element
diff --git a/features/first-line.yml b/features/first-line.yml
new file mode 100644
index 00000000000..dce475e9fc6
--- /dev/null
+++ b/features/first-line.yml
@@ -0,0 +1,10 @@
+name: ::first-line
+description: The `::first-line` CSS pseudo-element sets the styles of the first line of text in an element.
+spec: https://drafts.csswg.org/css-pseudo-4/#first-line-pseudo
+group: selectors
+caniuse: css-first-line
+status:
+  compute_from: css.selectors.first-line
+compat_features:
+  - css.selectors.first-line
+  - css.selectors.first-line.svg_text_element
diff --git a/features/first-line.yml.dist b/features/first-line.yml.dist
new file mode 100644
index 00000000000..aa5117f1658
--- /dev/null
+++ b/features/first-line.yml.dist
@@ -0,0 +1,35 @@
+# Generated from: first-line.yml
+# Do not edit this file by hand. Edit the source file instead!
+
+status:
+  baseline: high
+  baseline_low_date: 2015-07-29
+  baseline_high_date: 2018-01-29
+  support:
+    chrome: "1"
+    chrome_android: "18"
+    edge: "12"
+    firefox: "1"
+    firefox_android: "4"
+    safari: "1"
+    safari_ios: "1"
+compat_features:
+  # ⬇️ Same status as overall feature ⬇️
+  # baseline: high
+  # baseline_low_date: 2015-07-29
+  # baseline_high_date: 2018-01-29
+  # support:
+  #   chrome: "1"
+  #   chrome_android: "18"
+  #   edge: "12"
+  #   firefox: "1"
+  #   firefox_android: "4"
+  #   safari: "1"
+  #   safari_ios: "1"
+  - css.selectors.first-line
+
+  # baseline: false
+  # support:
+  #   firefox: "124"
+  #   firefox_android: "124"
+  - css.selectors.first-line.svg_text_element

From 1607a06bb20b14588864e406cd451c0d58047a89 Mon Sep 17 00:00:00 2001
From: James Stuckey Weber <james@oddbird.net>
Date: Sun, 29 Sep 2024 21:04:47 -0400
Subject: [PATCH 3/6] Add file-selector-button, before, after

---
 features/before-after.yml              | 13 ++++++
 features/before-after.yml.dist         | 64 ++++++++++++++++++++++++++
 features/file-selector-button.yml      |  6 +++
 features/file-selector-button.yml.dist | 17 +++++++
 features/placeholder.yml               |  2 +-
 features/text-decoration-selection.yml |  2 +-
 6 files changed, 102 insertions(+), 2 deletions(-)
 create mode 100644 features/before-after.yml
 create mode 100644 features/before-after.yml.dist
 create mode 100644 features/file-selector-button.yml
 create mode 100644 features/file-selector-button.yml.dist

diff --git a/features/before-after.yml b/features/before-after.yml
new file mode 100644
index 00000000000..db4124b81aa
--- /dev/null
+++ b/features/before-after.yml
@@ -0,0 +1,13 @@
+name: ::before and ::after
+description: The `::before` and `::after` CSS pseudo-elements set styles of the first and last children of an element. They often are used to add 4
+spec: https://drafts.csswg.org/css-pseudo-4/#generated-content
+caniuse: css-gencontent
+status:
+  compute_from:
+    - css.selectors.before
+    - css.selectors.after
+compat_features:
+  - css.selectors.before
+  - css.selectors.before.animation_and_transition_support
+  - css.selectors.after
+  - css.selectors.after.animation_and_transition_support
diff --git a/features/before-after.yml.dist b/features/before-after.yml.dist
new file mode 100644
index 00000000000..480a3356a2b
--- /dev/null
+++ b/features/before-after.yml.dist
@@ -0,0 +1,64 @@
+# Generated from: before-after.yml
+# Do not edit this file by hand. Edit the source file instead!
+
+status:
+  baseline: high
+  baseline_low_date: 2015-07-29
+  baseline_high_date: 2018-01-29
+  support:
+    chrome: "1"
+    chrome_android: "18"
+    edge: "12"
+    firefox: "1.5"
+    firefox_android: "4"
+    safari: "4"
+    safari_ios: "3.2"
+compat_features:
+  # baseline: high
+  # baseline_low_date: 2015-07-29
+  # baseline_high_date: 2018-01-29
+  # support:
+  #   chrome: "1"
+  #   chrome_android: "18"
+  #   edge: "12"
+  #   firefox: "1.5"
+  #   firefox_android: "4"
+  #   safari: "4"
+  #   safari_ios: "3"
+  - css.selectors.before
+
+  # ⬇️ Same status as overall feature ⬇️
+  # baseline: high
+  # baseline_low_date: 2015-07-29
+  # baseline_high_date: 2018-01-29
+  # support:
+  #   chrome: "1"
+  #   chrome_android: "18"
+  #   edge: "12"
+  #   firefox: "1.5"
+  #   firefox_android: "4"
+  #   safari: "4"
+  #   safari_ios: "3.2"
+  - css.selectors.after
+
+  # baseline: high
+  # baseline_low_date: ≤2017-03-27
+  # baseline_high_date: ≤2019-09-27
+  # support:
+  #   chrome: "26"
+  #   chrome_android: "26"
+  #   edge: "12"
+  #   firefox: "4"
+  #   firefox_android: "4"
+  #   safari: ≤10.1
+  #   safari_ios: ≤10.3
+  - css.selectors.before.animation_and_transition_support
+
+  # baseline: false
+  # support:
+  #   chrome: "26"
+  #   chrome_android: "26"
+  #   edge: "12"
+  #   firefox: "4"
+  #   firefox_android: "4"
+  - css.selectors.after.animation_and_transition_support
diff --git a/features/file-selector-button.yml b/features/file-selector-button.yml
new file mode 100644
index 00000000000..fd8d3feee55
--- /dev/null
+++ b/features/file-selector-button.yml
@@ -0,0 +1,6 @@
+name: ::file-selector-button
+description: The `::file-selector-button` CSS pseudo-element sets the styles on the button of a `<input type="file">` element.
+spec: https://drafts.csswg.org/css-pseudo-4/#file-selector-button-pseudo
+group: selectors
+compat_features:
+  - css.selectors.file-selector-button
diff --git a/features/file-selector-button.yml.dist b/features/file-selector-button.yml.dist
new file mode 100644
index 00000000000..4a84f652bdb
--- /dev/null
+++ b/features/file-selector-button.yml.dist
@@ -0,0 +1,17 @@
+# Generated from: file-selector-button.yml
+# Do not edit this file by hand. Edit the source file instead!
+
+status:
+  baseline: high
+  baseline_low_date: 2021-04-26
+  baseline_high_date: 2023-10-26
+  support:
+    chrome: "89"
+    chrome_android: "89"
+    edge: "89"
+    firefox: "82"
+    firefox_android: "82"
+    safari: "14.1"
+    safari_ios: "14.5"
+compat_features:
+  - css.selectors.file-selector-button
diff --git a/features/placeholder.yml b/features/placeholder.yml
index ffbd7c9d088..7d91d9362e8 100644
--- a/features/placeholder.yml
+++ b/features/placeholder.yml
@@ -1,7 +1,7 @@
 name: ::placeholder
 description: The `::placeholder` CSS pseudo-element sets the styles on text in `<input>` and `<textarea>` elements when no value is set.
 spec: https://drafts.csswg.org/css-pseudo-4/#placeholder-pseudo
-caniuse: https://caniuse.com/css-placeholder
+caniuse: css-placeholder
 group: selectors
 compat_features:
   - css.selectors.placeholder
diff --git a/features/text-decoration-selection.yml b/features/text-decoration-selection.yml
index 80c9bde4b0e..1344ca14169 100644
--- a/features/text-decoration-selection.yml
+++ b/features/text-decoration-selection.yml
@@ -1,6 +1,6 @@
 name: text-decoration in ::selection
 description: The `text-decoration` CSS property in a `::selection` rule sets the underline and other text decoration styles on the text a user has highlighted.
-spec: https://drafts.csswg.org/css-pseudo/#highlight-styling
+spec: https://drafts.csswg.org/css-pseudo-4/#highlight-styling
 group: selectors
 compat_features:
   - css.selectors.selection.text-decoration

From c4e5b05cc9634010860bd5e596ce1a318ca00a74 Mon Sep 17 00:00:00 2001
From: James Stuckey Weber <james@oddbird.net>
Date: Mon, 30 Sep 2024 09:25:58 -0400
Subject: [PATCH 4/6] Pseudo wording

---
 features/before-after.yml         | 2 +-
 features/file-selector-button.yml | 2 +-
 features/first-letter.yml         | 2 +-
 features/first-line.yml           | 2 +-
 features/placeholder-shown.yml    | 2 +-
 features/placeholder.yml          | 2 +-
 features/selection.yml            | 2 +-
 7 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/features/before-after.yml b/features/before-after.yml
index db4124b81aa..0f4574d4860 100644
--- a/features/before-after.yml
+++ b/features/before-after.yml
@@ -1,5 +1,5 @@
 name: ::before and ::after
-description: The `::before` and `::after` CSS pseudo-elements set styles of the first and last children of an element. They often are used to add 4
+description: The `::before` and `::after` CSS pseudo-elements selects the first and last children of an element for styling, and are often used with the `content` property to add generated cosmetic content.
 spec: https://drafts.csswg.org/css-pseudo-4/#generated-content
 caniuse: css-gencontent
 status:
diff --git a/features/file-selector-button.yml b/features/file-selector-button.yml
index fd8d3feee55..5185c1991ce 100644
--- a/features/file-selector-button.yml
+++ b/features/file-selector-button.yml
@@ -1,5 +1,5 @@
 name: ::file-selector-button
-description: The `::file-selector-button` CSS pseudo-element sets the styles on the button of a `<input type="file">` element.
+description: The `::file-selector-button` CSS pseudo-element selects the button of a `<input type="file">` element.
 spec: https://drafts.csswg.org/css-pseudo-4/#file-selector-button-pseudo
 group: selectors
 compat_features:
diff --git a/features/first-letter.yml b/features/first-letter.yml
index 1dfff67261e..43f6510a26a 100644
--- a/features/first-letter.yml
+++ b/features/first-letter.yml
@@ -1,5 +1,5 @@
 name: ::first-letter
-description: The `::first-letter` CSS pseudo-element sets the styles of the first letter in an element.
+description: The `::first-letter` CSS pseudo-element selects the first letter in an element for styling.
 spec: https://drafts.csswg.org/css-pseudo-4/#first-letter-pseudo
 group: selectors
 caniuse: css-first-letter
diff --git a/features/first-line.yml b/features/first-line.yml
index dce475e9fc6..a181687369a 100644
--- a/features/first-line.yml
+++ b/features/first-line.yml
@@ -1,5 +1,5 @@
 name: ::first-line
-description: The `::first-line` CSS pseudo-element sets the styles of the first line of text in an element.
+description: The `::first-line` CSS pseudo-element selects the first line of text in an element for styling.
 spec: https://drafts.csswg.org/css-pseudo-4/#first-line-pseudo
 group: selectors
 caniuse: css-first-line
diff --git a/features/placeholder-shown.yml b/features/placeholder-shown.yml
index 622bb373669..dbf558a796e 100644
--- a/features/placeholder-shown.yml
+++ b/features/placeholder-shown.yml
@@ -1,5 +1,5 @@
 name: :placeholder-shown
-description: The `:placeholder-shown` CSS pseudo-element sets the styles on `<input>` and `<textarea>` elements when no value is set and placeholder text is shown.
+description: The `:placeholder-shown` CSS pseudo-element selects `<input>` and `<textarea>` elements when no value is set and placeholder text is shown.
 spec: https://drafts.csswg.org/selectors-4/#placeholder
 caniuse: css-placeholder-shown
 group: selectors
diff --git a/features/placeholder.yml b/features/placeholder.yml
index 7d91d9362e8..b4ca2b160e6 100644
--- a/features/placeholder.yml
+++ b/features/placeholder.yml
@@ -1,5 +1,5 @@
 name: ::placeholder
-description: The `::placeholder` CSS pseudo-element sets the styles on text in `<input>` and `<textarea>` elements when no value is set.
+description: The `::placeholder` CSS pseudo-element selects text in `<input>` and `<textarea>` elements when no value is set.
 spec: https://drafts.csswg.org/css-pseudo-4/#placeholder-pseudo
 caniuse: css-placeholder
 group: selectors
diff --git a/features/selection.yml b/features/selection.yml
index e6aa5ad2dbe..eeefa19a091 100644
--- a/features/selection.yml
+++ b/features/selection.yml
@@ -1,5 +1,5 @@
 name: ::selection
-description: The `::selection` CSS pseudo-element sets styles on the text a user has highlighted.
+description: The `::selection` CSS pseudo-element selects text a user has highlighted.
 spec: https://drafts.csswg.org/css-pseudo-4/#selectordef-selection
 caniuse: css-selection
 group: selectors

From 2929dbd839914f3db152c68cee16c7d706c7408a Mon Sep 17 00:00:00 2001
From: James Stuckey Weber <james@oddbird.net>
Date: Mon, 30 Sep 2024 09:28:30 -0400
Subject: [PATCH 5/6] Fix typo

---
 features/before-after.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/features/before-after.yml b/features/before-after.yml
index 0f4574d4860..1e44ae22c47 100644
--- a/features/before-after.yml
+++ b/features/before-after.yml
@@ -1,5 +1,5 @@
 name: ::before and ::after
-description: The `::before` and `::after` CSS pseudo-elements selects the first and last children of an element for styling, and are often used with the `content` property to add generated cosmetic content.
+description: The `::before` and `::after` CSS pseudo-elements select the first and last children of an element for styling, and are often used with the `content` property to add generated cosmetic content.
 spec: https://drafts.csswg.org/css-pseudo-4/#generated-content
 caniuse: css-gencontent
 status:

From f20bcd8a1e8938e6fda7f0220fb9431a3e98ef84 Mon Sep 17 00:00:00 2001
From: James Stuckey Weber <james@oddbird.net>
Date: Mon, 30 Sep 2024 12:25:04 -0400
Subject: [PATCH 6/6] Review

---
 features/before-after.yml      | 2 +-
 features/placeholder-shown.yml | 2 +-
 features/placeholder.yml       | 3 ++-
 3 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/features/before-after.yml b/features/before-after.yml
index 1e44ae22c47..e7af46e4a00 100644
--- a/features/before-after.yml
+++ b/features/before-after.yml
@@ -1,5 +1,5 @@
 name: ::before and ::after
-description: The `::before` and `::after` CSS pseudo-elements select the first and last children of an element for styling, and are often used with the `content` property to add generated cosmetic content.
+description: The `::before` and `::after` CSS pseudo-elements select inline boxes preceding and following an element. They are often used with the `content` property to generate cosmetic content.
 spec: https://drafts.csswg.org/css-pseudo-4/#generated-content
 caniuse: css-gencontent
 status:
diff --git a/features/placeholder-shown.yml b/features/placeholder-shown.yml
index dbf558a796e..da5aca117eb 100644
--- a/features/placeholder-shown.yml
+++ b/features/placeholder-shown.yml
@@ -1,5 +1,5 @@
 name: :placeholder-shown
-description: The `:placeholder-shown` CSS pseudo-element selects `<input>` and `<textarea>` elements when no value is set and placeholder text is shown.
+description: The `:placeholder-shown` CSS pseudo-element selects `<input>` and `<textarea>` elements when no value is set and the element's `placeholder` attribute is not empty. Not to be confused with `::placeholder`, which selects the placeholder text itself.
 spec: https://drafts.csswg.org/selectors-4/#placeholder
 caniuse: css-placeholder-shown
 group: selectors
diff --git a/features/placeholder.yml b/features/placeholder.yml
index b4ca2b160e6..88637eb5ada 100644
--- a/features/placeholder.yml
+++ b/features/placeholder.yml
@@ -1,7 +1,8 @@
 name: ::placeholder
-description: The `::placeholder` CSS pseudo-element selects text in `<input>` and `<textarea>` elements when no value is set.
+description: The `::placeholder` CSS pseudo-element selects help text in `<input>` and `<textarea>` elements when no value is set.
 spec: https://drafts.csswg.org/css-pseudo-4/#placeholder-pseudo
 caniuse: css-placeholder
 group: selectors
+# TODO: create some kind of "input placeholders" feature when https://github.com/web-platform-dx/web-features/issues/971 is resolved, combining placeholder selectors and the element attr
 compat_features:
   - css.selectors.placeholder