docs(css): Add support for <string> in syntax descriptor of @Prop…

…erty at-rule (#36655)

* update @Property descriptors

* update syntax

* revert js code removal

* update release note

* Update files/en-us/web/css/@property/index.md

* Apply suggestions from code review

* Update files/en-us/web/css/@property/index.md

---------

Co-authored-by: Brian Thomas Smith <brian@smith.berlin>

files/en-us/mozilla/firefox/releases/128/index.md

@@ -18,6 +18,7 @@ This article provides information about the changes in Firefox 128 that affect d
 
 - [Relative color syntax](/en-US/docs/Web/CSS/CSS_colors/Relative_colors) is now enabled by default. Relative color syntax allows you to create a color value relative to an origin color, and can allow you to change a color in a different [color space](/en-US/docs/Glossary/Color_space) using [color functions](/en-US/docs/Web/CSS/CSS_colors#functions) ([Firefox bug 1900251](https://bugzil.la/1900251)).
 - The [`content`](/en-US/docs/Web/CSS/content) property now supports [alternative text](/en-US/docs/Web/CSS/content#alternative_text) for content that includes an image. The alternative text is then exposed to the browsers accessibility tree. (See [Firefox bug 1281158](https://bugzil.la/1281158) and [Firefox bug 1896047](https://bugzil.la/1896047)).
+- The [`syntax`](/en-US/docs/Web/CSS/@property/syntax) descriptor of the {{cssxref("@property")}} at-rule now supports the `<string>` syntax component name. (See [Firefox bug 1846635](https://bugzil.la/1846635)).
 
 #### Removals
 

files/en-us/web/css/@property/index.md

@@ -7,47 +7,51 @@ browser-compat: css.at-rules.property
 
 {{CSSRef}}
 
-The **`@property`** [CSS](/en-US/docs/Web/CSS) [at-rule](/en-US/docs/Web/CSS/At-rule) is part of the [CSS Houdini](/en-US/docs/Web/API/Houdini_APIs) umbrella of APIs. It allows developers to explicitly define their [CSS custom properties](/en-US/docs/Web/CSS/--*), allowing for property type checking and constraining, setting default values, and defining whether a custom property can inherit values or not.
+The **`@property`** [CSS](/en-US/docs/Web/CSS) [at-rule](/en-US/docs/Web/CSS/At-rule) is part of the [CSS Houdini](/en-US/docs/Web/API/Houdini_APIs) set of APIs. It allows developers to explicitly define [CSS custom properties](/en-US/docs/Web/CSS/--*), allowing for property type checking and constraining, setting default values, and defining whether a custom property can inherit values or not.
 
-The `@property` rule represents a custom property registration directly in a stylesheet without having to run any JS. Valid `@property` rules result in a registered custom property, as if {{domxref('CSS.registerProperty_static', 'registerProperty()')}} had been called with equivalent parameters.
+The `@property` rule represents a custom property registration directly in a stylesheet without having to run any JavaScript. Valid `@property` rules result in a registered custom property, which is similar to calling {{domxref('CSS.registerProperty_static', 'registerProperty()')}} with equivalent parameters.
 
 ## Syntax
 
 ```css
-@property --property-name {
-  syntax: "<color>";
+@property --rotation {
+  syntax: "<angle>";
   inherits: false;
-  initial-value: #c0ffee;
+  initial-value: 45deg;
 }
 ```
 
+The custom property name is a [`<dashed-ident>`](/en-US/docs/Web/CSS/dashed-ident) that starts with `--` and is followed by a valid, user-defined identifier. It is case-sensitive.
+
 ### Descriptors
 
 - {{cssxref("@property/syntax","syntax")}}
-
-  - : Describes the allowable syntax for the property. May be a `<length>`, `<number>`, `<percentage>`, `<length-percentage>`, `<color>`, `<image>`, `<url>`, `<integer>`, `<angle>`, `<time>`, `<resolution>`, `<transform-function>`, or `<custom-ident>`, or a list of data type and keyword values.
-
-    The `+` (space-separated) and `#` (comma-separated) multipliers indicate that a list of values is expected, for example `<color>#` means a comma-separated list of `<color>` values is the expected syntax.
-
-    Vertical lines (`|`) can create "or" conditions for the expected syntax, for example `<length> | auto` accepts a `<length>` or `auto`, and `<color># | <integer>#` expects a comma-separated list of `<color>` values or a comma-separated list of `<integer>` values.
-
+  - : A string that describes the allowed value types for the registered custom property.
+    May be a data type name (such as `<color>`, `<length>`, or `<number>`, etc.), with multipliers (`+`, `#`) and combinators (`|`), or a custom ident.
+    See the [syntax](/en-US/docs/Web/CSS/@property/syntax) descriptor page for more details.
 - {{cssxref("@property/inherits","inherits")}}
-  - : Controls whether the custom property registration specified by `@property` inherits by default.
+  - : A boolean value that controls whether the custom property registration specified by `@property` inherits by default.
 - {{cssxref("@property/initial-value","initial-value")}}
-  - : Sets the initial value for the property.
+  - : A value that sets the starting value for the property.
+
+## Description
 
-The `@property` rule must include both the {{cssxref("@property/syntax","syntax")}} and {{cssxref("@property/inherits","inherits")}} descriptors; if either are missing, the entire `@property` rule is invalid and ignored.
-The {{cssxref("@property/initial-value","initial-value")}} descriptor is also required, unless the syntax is the [`*` universal syntax definition](https://drafts.css-houdini.org/css-properties-values-api/#universal-syntax-definition) (e.g., `syntax: "*"`).
-If the `initial-value` descriptor is required and omitted, the entire `@property` rule is invalid and ignored.
+The following conditions must be met for the `@property` rule to be valid:
 
-Unknown descriptors are invalid and ignored, but do not invalidate the `@property` rule.
+- The `@property` rule must include both the {{cssxref("@property/syntax","syntax")}} and {{cssxref("@property/inherits","inherits")}} descriptors.
+  If either is missing, the entire `@property` rule is invalid and ignored.
+- The {{cssxref("@property/initial-value","initial-value")}} descriptor is optional if the value of the `syntax` descriptor is the universal syntax definition (that is, `syntax: "*"`).
+  If the `initial-value` descriptor is required but omitted, the entire `@property` rule is invalid and ignored.
+- Unknown descriptors are invalid and ignored, but do not invalidate the `@property` rule.
 
 ## Formal syntax
 
 {{csssyntax}}
 
 ## Examples
 
+### Using `@property` to register and use a custom property
+
 In this example, we define two custom properties, `--item-size` and `--item-color`, that we'll use to define the size (width and height) and background color of the three following items.
 
 ```html

files/en-us/web/css/@property/inherits/index.md

@@ -7,25 +7,20 @@ browser-compat: css.at-rules.property.inherits
 
 {{CSSRef}}
 
-The **`inherits`** [CSS](/en-US/docs/Web/CSS) descriptor is required when using the {{cssxref("@property")}} [at-rule](/en-US/docs/Web/CSS/At-rule) and controls whether the custom property registration specified by `@property` inherits by default.
+The **`inherits`** [CSS](/en-US/docs/Web/CSS) descriptor of the {{cssxref("@property")}} [at-rule](/en-US/docs/Web/CSS/At-rule) controls whether or not the registered [CSS custom property](/en-US/docs/Web/CSS/--*) inherits by default.
+It is a required descriptor; if missing or invalid, the entire `@property` rule is invalid and ignored.
 
 ## Syntax
 
 ```css
-@property --property-name {
-  syntax: "<color>";
-  inherits: false;
-  initial-value: #c0ffee;
-}
+/* Custom property does not inherit values */
+inherits: false;
 
-@property --property-name {
-  syntax: "<color>";
-  inherits: true;
-  initial-value: #c0ffee;
-}
+/* Custom property inherits values */
+inherits: true;
 ```
 
-## Values
+### Values
 
 - `true`
   - : The property inherits by default.
@@ -42,9 +37,9 @@ The **`inherits`** [CSS](/en-US/docs/Web/CSS) descriptor is required when using
 
 ## Examples
 
-Add type checking to `--my-color` [custom property](/en-US/docs/Web/CSS/--*), as a color, a default value, and not allow it to inherit its value:
+### Setting inheritance behavior of a custom property
 
-Using [CSS](/en-US/docs/Web/CSS) {{cssxref('@property')}} [at-rule](/en-US/docs/Web/CSS/At-rule):
+This example shows how to define a custom property `--my-color` that does not inherit its value from its parent elements:
 
 ```css
 @property --my-color {
@@ -75,6 +70,7 @@ window.CSS.registerProperty({
 
 ## See also
 
+- Other {{cssxref("@property")}} descriptors: {{cssxref("@property/initial-value", "initial-value")}} and {{cssxref("@property/syntax","syntax")}}
 - [CSS Properties and Values API](/en-US/docs/Web/API/CSS_Properties_and_Values_API)
 - [CSS Painting API](/en-US/docs/Web/API/CSS_Painting_API)
 - [CSS Typed Object Model](/en-US/docs/Web/API/CSS_Typed_OM_API)

files/en-us/web/css/@property/initial-value/index.md

@@ -7,29 +7,24 @@ browser-compat: css.at-rules.property.initial-value
 
 {{CSSRef}}
 
-The **`initial-value`** [CSS](/en-US/docs/Web/CSS) descriptor is required when using the {{cssxref("@property")}} [at-rule](/en-US/docs/Web/CSS/At-rule) unless the syntax accepts any valid token stream. It sets the initial-value for the property.
-
-The value chosen as the `initial-value` must parse correctly according to the syntax definition. Therefore, if syntax is `<color>` then the initial-value must be a valid {{cssxref("color")}} value.
+The **`initial-value`** descriptor of the {{cssxref("@property")}} [at-rule](/en-US/docs/Web/CSS/At-rule) specifies the initial value for the registered [CSS custom property](/en-US/docs/Web/CSS/--*).
+It is a required descriptor unless the {{cssxref("@property/syntax", "syntax")}} descriptor value is the universal syntax (`*`).
+If required but missing or invalid, the entire `@property` rule is invalid and ignored.
 
 ## Syntax
 
 ```css
-@property --property-name {
-  syntax: "<color>";
-  inherits: false;
-  initial-value: #c0ffee;
-}
+/* Set initial color value */
+initial-value: rebeccapurple;
 
-@property --property-name {
-  syntax: "<color>";
-  inherits: true;
-  initial-value: #c0ffee;
-}
+/* Set initial length value */
+initial-value: 2rem;
 ```
 
-## Values
+### Values
 
-A string with a value which is a correct value for the chosen `syntax`.
+A value that matches the type specified in the {{cssxref("@property/syntax", "syntax")}} descriptor.
+For example, if `syntax` is `<color>`, then the `initial-value` must be a valid {{cssxref("color")}} value.
 
 ## Formal definition
 
@@ -41,9 +36,9 @@ A string with a value which is a correct value for the chosen `syntax`.
 
 ## Examples
 
-Add type checking to `--my-color` [custom property](/en-US/docs/Web/CSS/--*), as a color, the initial-value being a valid color:
+### Setting an initial value for a custom property
 
-Using [CSS](/en-US/docs/Web/CSS) {{cssxref('@property')}} [at-rule](/en-US/docs/Web/CSS/At-rule):
+This example shows how to define a custom property `--my-color` with an initial color value of `#c0ffee`. This initial value will be used when the property is not inherited (`inherits: false`) and no other value is set on the element.
 
 ```css
 @property --my-color {
@@ -74,6 +69,7 @@ window.CSS.registerProperty({
 
 ## See also
 
+- Other {{cssxref("@property")}} descriptors: {{cssxref("@property/inherits","inherits")}} and {{cssxref("@property/syntax", "syntax")}}
 - [CSS Properties and Values API](/en-US/docs/Web/API/CSS_Properties_and_Values_API)
 - [CSS Painting API](/en-US/docs/Web/API/CSS_Painting_API)
 - [CSS Typed Object Model](/en-US/docs/Web/API/CSS_Typed_OM_API)

files/en-us/web/css/@property/syntax/index.md

@@ -7,54 +7,86 @@ browser-compat: css.at-rules.property.syntax
 
 {{CSSRef}}
 
-The **`syntax`** [CSS](/en-US/docs/Web/CSS) descriptor is required when using the {{cssxref("@property")}} [at-rule](/en-US/docs/Web/CSS/At-rule) and describes the allowable syntax for the property.
+The **`syntax`** descriptor of the {{cssxref("@property")}} [at-rule](/en-US/docs/Web/CSS/At-rule) defines the allowed value types for the registered [CSS custom property](/en-US/docs/Web/CSS/--*).
+It controls how the property's specified value is processed to derive the {{cssxref("computed_value","computed value")}}.
+It is a required descriptor; if missing or invalid, the entire `@property` rule is invalid and ignored.
 
 ## Syntax
 
-The following are all valid syntax strings:
-
 ```css
-syntax: "<color>"; /* accepts a color */
+/* A data type name */
+syntax: "<color>";
+
+/* A '|' combinator for multiple data types */
+syntax: "<length> | <percentage>";
+
+/* Space-separated list of values */
+syntax: "<color>+";
+
+/* Comma-separated list of values */
+syntax: "<length>#";
 
-syntax: "<length> | <percentage>"; /* accepts lengths or percentages but not calc expressions with a combination of the two */
+/* Keywords */
+syntax: "small | medium | large";
 
-syntax: "small | medium | large"; /* accepts one of these values set as custom idents. */
+/* Combination of data type and keyword */
+syntax: "<length> | auto";
 
-syntax: "*"; /* any valid token */
+/* Universal syntax value */
+syntax: "*";
 ```
 
-## Values
+### Values
 
-A string with a supported syntax as defined by the specification. Supported syntaxes are a subset of [CSS types](/en-US/docs/Web/CSS/CSS_Types). These may be used alone, or a number of types can be used in combination.
+A string (known as the syntax string) that defines the allowed values.
+It can be one of the following:
 
-- `"<length>"`
-  - : Any valid {{cssxref("&lt;length&gt;")}} values.
-- `"<number>"`
-  - : Any valid {{cssxref("&lt;number&gt;")}} values.
-- `"<percentage>"`
-  - : Any valid {{cssxref("&lt;percentage&gt;")}} values.
-- `"<length-percentage>"`
-  - : Any valid {{cssxref("&lt;length-percentage&gt;")}} values.
+- One or more syntax component names, which can be:
+  - Data type names (written with angle brackets, such as `<color>` or `<length>`)
+  - Keywords (written without angle brackets, such as `auto` or `none`)
+- The universal syntax `*`, which accepts any valid CSS value.
+  It cannot be multiplied or combined with other syntax components.
+
+The syntax component names can be used alone or multiplied and combined in different ways:
+
+- The `+` (space-separated) and `#` (comma-separated) multipliers indicate that a list of values is expected.
+  For example, `<color>#` means a comma-separated list of `<color>` values is the expected syntax.
+
+- The vertical line (`|`) combinator can create "or" conditions for the expected syntax.
+  For example, `<length> | auto` accepts `<length>` or `auto`, and `<color># | <integer>#` expects a comma-separated list of `<color>` values or a comma-separated list of `<integer>` values.
+
+The following syntax component names are supported:
+
+- `"<angle>"`
+  - : Accepts any valid {{cssxref("&lt;angle&gt;")}} value.
 - `"<color>"`
-  - : Any valid {{cssxref("&lt;color&gt;")}} values.
+  - : Accepts any valid {{cssxref("&lt;color&gt;")}} value.
+- `"<custom-ident>"`
+  - : Accepts any valid {{cssxref("&lt;custom-ident&gt;")}} value.
 - `"<image>"`
-  - : Any valid {{cssxref("&lt;image&gt;")}} values.
-- `"<url>"`
-  - : Any valid {{cssxref("url_value", "&lt;url&gt;")}} values.
+  - : Accepts any valid {{cssxref("&lt;image&gt;")}} value.
 - `"<integer>"`
-  - : Any valid {{cssxref("&lt;integer&gt;")}} values.
-- `"<angle>"`
-  - : Any valid {{cssxref("&lt;angle&gt;")}} values.
-- `"<time>"`
-  - : Any valid {{cssxref("&lt;time&gt;")}} values.
+  - : Accepts any valid {{cssxref("&lt;integer&gt;")}} value.
+- `"<length>"`
+  - : Accepts any valid {{cssxref("&lt;length&gt;")}} value.
+- `"<length-percentage>"`
+  - : Accepts any valid {{cssxref("&lt;length&gt;")}} or {{cssxref("&lt;percentage&gt;")}} value and any valid {{cssxref("calc", "calc()")}} expression combining `<length>` and `<percentage>` values.
+- `"<number>"`
+  - : Accepts any valid {{cssxref("&lt;number&gt;")}} value.
+- `"<percentage>"`
+  - : Accepts any valid {{cssxref("&lt;percentage&gt;")}} value.
 - `"<resolution>"`
-  - : Any valid {{cssxref("&lt;resolution&gt;")}} values.
+  - : Accepts any valid {{cssxref("&lt;resolution&gt;")}} value.
+- `"<string>"`
+  - : Accepts any valid {{cssxref("&lt;string&gt;")}} value.
+- `"<time>"`
+  - : Accepts any valid {{cssxref("&lt;time&gt;")}} value.
 - `"<transform-function>"`
-  - : Any valid {{cssxref("&lt;transform-function&gt;")}} values.
-- `"<custom-ident>"`
-  - : Any valid {{cssxref("&lt;custom-ident&gt;")}} values.
+  - : Accepts any valid {{cssxref("&lt;transform-function&gt;")}} value.
 - `"<transform-list>"`
-  - : A list of valid {{cssxref("&lt;transform-function&gt;")}} values.
+  - : Accepts a list of valid {{cssxref("&lt;transform-function&gt;")}} values. It is equivalent to `"<transform-function>+"`.
+- `"<url>"`
+  - : Accepts any valid {{cssxref("url_value", "&lt;url&gt;")}} value.
 
 ## Formal definition
 
@@ -66,9 +98,9 @@ A string with a supported syntax as defined by the specification. Supported synt
 
 ## Examples
 
-Add type checking to `--my-color` [custom property](/en-US/docs/Web/CSS/--*), using the `<color>` syntax:
+### Registering a custom property with type checking
 
-Using [CSS](/en-US/docs/Web/CSS) {{cssxref('@property')}} [at-rule](/en-US/docs/Web/CSS/At-rule):
+This example shows how to define a custom property `--my-color` that allows only `<color>` values:
 
 ```css
 @property --my-color {
@@ -99,6 +131,7 @@ window.CSS.registerProperty({
 
 ## See also
 
+- Other {{cssxref("@property")}} descriptors: {{cssxref("@property/inherits","inherits")}} and {{cssxref("@property/initial-value", "initial-value")}}
 - [CSS Properties and Values API](/en-US/docs/Web/API/CSS_Properties_and_Values_API)
 - [CSS Painting API](/en-US/docs/Web/API/CSS_Painting_API)
 - [CSS Typed Object Model](/en-US/docs/Web/API/CSS_Typed_OM_API)