From 63ea7795596d2e3500b0fc59748583a5539534dd Mon Sep 17 00:00:00 2001
From: Masafumi Koba <473530+ybiquitous@users.noreply.github.com>
Date: Fri, 13 Dec 2024 09:24:20 +0900
Subject: [PATCH] Document `at-rule-property-required-list`  difference between
 properties and descriptors (#8185)

This change was produced by the discussion on <https://github.com/stylelint/stylelint/issues/8148#issuecomment-2531031990>.

We probably should have named the `at-rule-property-required-list` as `at-rule-descriptor-required-list`
because declarations in at-rules are semantically descriptors rather than properties.

See also <https://drafts.csswg.org/css-syntax/#declaration>.

Co-authored-by: Richard Hallows <jeddy3@users.noreply.github.com>
---
 docs/user-guide/rules.md                           | 2 +-
 lib/rules/at-rule-property-required-list/README.md | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/user-guide/rules.md b/docs/user-guide/rules.md
index 82e7b27d79..5e840fc584 100644
--- a/docs/user-guide/rules.md
+++ b/docs/user-guide/rules.md
@@ -155,7 +155,7 @@ Allow, disallow or require things with these `allowed-list`, `disallowed-list`,
 | [`at-rule-allowed-list`](../../lib/rules/at-rule-allowed-list/README.md)<br/>Specify a list of allowed at-rules. | | |
 | [`at-rule-disallowed-list`](../../lib/rules/at-rule-disallowed-list/README.md)<br/>Specify a list of disallowed at-rules. | | |
 | [`at-rule-no-vendor-prefix`](../../lib/rules/at-rule-no-vendor-prefix/README.md)<br/>Disallow vendor prefixes for at-rules. | ✅ | 🔧 |
-| [`at-rule-property-required-list`](../../lib/rules/at-rule-property-required-list/README.md)<br/>Specify a list of required properties for an at-rule. | | |
+| [`at-rule-property-required-list`](../../lib/rules/at-rule-property-required-list/README.md)<br/>Specify a list of required descriptors for an at-rule. | | |
 <!-- prettier-ignore-end -->
 
 #### Color
diff --git a/lib/rules/at-rule-property-required-list/README.md b/lib/rules/at-rule-property-required-list/README.md
index 9598405f37..fa5fc4297b 100644
--- a/lib/rules/at-rule-property-required-list/README.md
+++ b/lib/rules/at-rule-property-required-list/README.md
@@ -1,19 +1,19 @@
 # at-rule-property-required-list
 
-Specify a list of required properties for an at-rule.
+Specify a list of required descriptors (previously labelled as properties) for an at-rule.
 
 <!-- prettier-ignore -->
 ```css
     @font-face { font-display: swap; font-family: 'foo'; }
 /**  ↑           ↑                   ↑
- *  At-rule and required property names */
+ *  At-rule and required descriptor names */
 ```
 
 The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
 
 ## Options
 
-`object`: `{ "at-rule-name": ["array", "of", "properties"]|"property" }`
+`object`: `{ "at-rule-name": ["array", "of", "descriptors"]|"descriptor" }`
 
 Given: