docs(css): add module page for CSS Properties and Values API

files/en-us/web/api/css/index.md

@@ -3,6 +3,9 @@ title: CSS
 slug: Web/API/CSS
 page-type: web-api-interface
 browser-compat: api.CSS
+spec-urls:
+  - https://drafts.csswg.org/cssom/#namespacedef-css
+  - https://www.w3.org/TR/css-properties-values-api-1/
 ---
 
 {{APIRef("CSSOM")}}

files/en-us/web/css/--_star_/index.md

@@ -86,6 +86,7 @@ Custom properties are scoped to the element(s) they are declared on, and partici
 
 ## See also
 
-- [Using CSS variables](/en-US/docs/Web/CSS/Using_CSS_custom_properties)
 - The {{cssxref("var", "var()")}} function
 - {{cssxref("@property")}} at-rule
+- [Using CSS custom properties (variables)](/en-US/docs/Web/CSS/Using_CSS_custom_properties) guide
+- [CSS custom properties for cascading variables](/en-US/docs/Web/CSS/CSS_cascading_variables) module

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

@@ -24,15 +24,21 @@ The `@property` rule represents a custom property registration directly in a sty
 ### Descriptors
 
 - {{cssxref("@property/syntax","syntax")}}
-  - : Describes the allowable syntax for the property.
+
+  - : 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.
+
 - {{cssxref("@property/inherits","inherits")}}
   - : 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 valid `@property` rule represents a custom property registration, with the property name being the serialization of the in the rule's prelude.
-
-`@property` rules require a {{cssxref("@property/syntax","syntax")}} and {{cssxref("@property/inherits","inherits")}} descriptor; if either are missing, the entire rule is invalid and must be ignored. The {{cssxref("@property/initial-value","initial-value")}} descriptor is optional only if the syntax is the <a href="https://drafts.css-houdini.org/css-properties-values-api/#universal-syntax-definition">universal syntax definition</a>, otherwise the descriptor is required; if it's missing, the entire rule is invalid and must be ignored.
+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., `initial-value: *`).
+If the `initial-value` descriptor is required and omitted, the entire `@property` rule is invalid and ignored.
 
 Unknown descriptors are invalid and ignored, but do not invalidate the `@property` rule.
 
@@ -126,7 +132,10 @@ For item three, the `--item-size` value gets set to `1000px`. While `1000px` is
 
 ## See also
 
+- {{cssxref("var")}}
 - [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)
 - [CSS Houdini](/en-US/docs/Web/Guide/Houdini)
+- [Using CSS custom properties (variables)](/en-US/docs/Web/CSS/Using_CSS_custom_properties) guide
+- [CSS custom properties for cascading variables](/en-US/docs/Web/CSS/CSS_cascading_variables) module

files/en-us/web/css/css_cascading_variables/index.md

@@ -1,20 +1,131 @@
 ---
-title: CSS cascading variables
+title: CSS custom properties for cascading variables
 slug: Web/CSS/CSS_cascading_variables
 page-type: css-module
 spec-urls: https://drafts.csswg.org/css-variables/
 ---
 
 {{CSSRef}}
 
-The **CSS cascading variables** module adds support for cascading variables in all CSS properties and also lets you create custom properties to define these variables.
+The **CSS custom properties for cascading variables** module adds support for cascading variables in CSS properties and lets you create custom properties to define these variables along with the mechanisms to use custom properties as the values for other CSS properties.
+
+When working with CSS, you often end up reusing common project-specific values such as widths that work well with your layout, or a set of colors for your color scheme.
+One way of managing repetition in stylesheets is to define a value once and use it many times in other places.
+Custom properties let you create and define custom variables that can be reused, simplifying complex or repetitive rules and making them easier to read and maintain.
+For example, `--dark-grey-text` and `--dark-background` are easier to understand than hexadecimal colors such as `#323831`, and the context of how you use them is more obvious, too.
+
+## Custom properties in action
+
+To see how custom properties can be used, move the input slider left to right.
+
+```html hidden
+<div class="container">
+  <div id="color-1">--hue</div>
+  <div id="color-2">--hue + 10</div>
+  <div id="color-3">--hue + 20</div>
+  <div id="color-4">--hue + 30</div>
+  <div id="color-5">--hue + 40</div>
+  <div id="color-6">--hue + 50</div>
+  <div id="color-7">--hue + 60</div>
+  <div id="color-8">--hue + 70</div>
+</div>
+<input type="range" min="0" max="360" value="0" step="0.1" id="hue" />
+```
+
+```js hidden
+const hue = document.querySelector("#hue");
+
+const updateHue = () => {
+  document.documentElement.style.setProperty("--hue", hue.value);
+};
+
+hue.addEventListener("input", updateHue);
+```
+
+```css hidden
+.container {
+  display: grid;
+  font-family: sans-serif;
+  color: white;
+  gap: 0.5rem;
+  grid-template-columns: repeat(4, 1fr);
+  margin-bottom: 1rem;
+}
+.container div {
+  border-radius: 0.5rem;
+  padding: 1rem;
+}
+
+input {
+  width: 100%;
+  margin: 0;
+}
+
+:root {
+  --hue: 0;
+}
+
+#color-1 {
+  background-color: hsl(var(--hue) 50% 50%);
+}
+#color-2 {
+  background-color: hsl(calc(var(--hue) + 10) 50% 50%);
+}
+#color-3 {
+  background-color: hsl(calc(var(--hue) + 20) 50% 50%);
+}
+#color-4 {
+  background-color: hsl(calc(var(--hue) + 30) 50% 50%);
+}
+#color-5 {
+  background-color: hsl(calc(var(--hue) + 40) 50% 50%);
+}
+#color-6 {
+  background-color: hsl(calc(var(--hue) + 50) 50% 50%);
+}
+#color-7 {
+  background-color: hsl(calc(var(--hue) + 60) 50% 50%);
+}
+#color-8 {
+  background-color: hsl(calc(var(--hue) + 70) 50% 50%);
+}
+```
+
+{{EmbedLiveSample("",600,160)}}
+
+Each color swatch increments the {{cssxref("hue")}} value by 10 degrees, setting the {{cssxref("background-color")}} using the {{cssxref("color_value/hsl", "hsl()")}} {{cssxref("&lt;color&gt;")}} function (`hsl(var(--hue) 50% 50%);`). As the slider's value changes from 0 up to 360, the value of the `--hue` [custom property](/en-US/docs/Web/CSS/--*) is updated, updating the background color of each box inside the grid.
 
 ## Reference
 
 ### Properties
 
 - {{cssxref("--*")}}
 
+### Functions
+
+- {{cssxref("var")}}
+
+## Guides
+
+- [Using CSS custom properties (variables)](/en-US/docs/Web/CSS/Using_CSS_custom_properties)
+  - : Explains how to use custom properties in CSS and JavaScript, with hints on handling undefined and invalid values, fallbacks, and inheritance.
+
+- [Invalid custom properties](/en-US/docs/Web/CSS/CSS_syntax/Error_handling#invalid_custom_properties)
+  - :  Explains how browsers handle property values when a custom property's value is an invalid data type for that property.
+
+## Related concepts
+
+- [CSS Properties and Values API](/en-US/docs/Web/CSS/CSS_properties_and_values_API) module
+  - [`@property`](/en-US/docs/Web/CSS/@property) at-rule
+  - [`CSS.registerProperty()`](/en-US/docs/Web/API/CSS/registerProperty_static) method
+
 ## Specifications
 
 {{Specifications}}
+
+## See also
+
+- [CSS cascade and inheritance](/en-US/docs/Web/CSS/CSS_cascade) module
+- [CSS `env()`](/en-US/docs/Web/CSS/env) function
+- [CSS `calc()`](/en-US/docs/Web/CSS/calc) function
+- [`getPropertyValue()`](/en-US/docs/Web/API/CSSStyleDeclaration/getPropertyValue) method

files/en-us/web/css/css_properties_and_values_api/index.md

@@ -0,0 +1,106 @@
+---
+title: CSS properties and values API
+slug: Web/CSS/CSS_properties_and_values_API
+page-type: css-module
+spec-urls: https://www.w3.org/TR/css-properties-values-api-1/
+---
+
+{{CSSRef}}
+
+The **CSS properties and values API** module defines a method for registering new CSS properties, defining the property's data type, inheritance behavior, and, optionally, an initial value. This API expands on [CSS custom properties for cascading variables](Web/CSS/CSS_cascading_variables) module, which allows authors to define custom properties in CSS using [two dash syntax (`--`)](/en-US/docs/Web/CSS/--*). The CSS properties and values API is part of the [CSS Houdini](/en-US/docs/Web/CSS/CSS_houdini) umbrella of APIs.
+
+Custom properties let you reuse values across a project to simplify complex or repetitive stylesheets. Basic custom properties are defined in the [CSS custom properties for cascading variables](Web/CSS/CSS_cascading_variables) module. The CSS properties and values API expands on that module, enabling adding metadata to custom properties using CSS with the [`@property`](/en-US/docs/Web/CSS/@property) at-rule or, alternatively, using JavaScript's {{domxref('CSS/registerProperty_static', 'CSS.registerProperty')}} method.
+
+Whether registered with CSS or JavaScript, setting metadata on custom properties provides for an expected data type that the browser can use depending on the context, defines an initial value, and lets you control inheritance.
+
+CSS properties and values API custom property registration is more robust than the more basic CSS cascading variable custom property declaration, especially when it comes to transitioning and animating values as browsers can interpolate between custom values of this type, whereas properties that use [two dash syntax (`--`)](/en-US/docs/Web/CSS/--*) behave more like a string substitution.
+
+## Properties and values API in action
+
+To see how custom properties and values can be used via API, hover over the box below.
+
+```js hidden
+CSS.registerProperty({
+  name: "--stop-color",
+  syntax: "<color>",
+  inherits: false,
+  initialValue: "cornflowerblue",
+});
+```
+
+```css hidden
+.box {
+  padding: 1rem;
+  width: 90%;
+  height: 4rem;
+  font-family: sans-serif;
+  font-size: large;
+  color: white;
+  border-radius: 0.5rem;
+}
+
+.box {
+  background: linear-gradient(to right, var(--stop-color), lavenderblush);
+  transition: --stop-color 2s;
+}
+
+.box:hover {
+  --stop-color: aquamarine;
+}
+```
+
+```html hidden
+<div class="box"><p>Linear gradient with transition</p></div>
+```
+
+{{EmbedLiveSample("",600,120)}}
+
+The box has a [backround](/en-US/docs/Web/CSS/background) consisting of a [linear gradient](/en-US/docs/Web/CSS/gradient/linear-gradient) from `--stop-color` (the custom property) to [`lavenderblush`](/en-US/docs/Web/CSS/named-color).
+The value of `--stop-color` is set to `cornflowerblue` at first, but when you hover over the box, `--stop-color` [transitions](/en-US/docs/Web/CSS/transition) to `aquamarine` over two seconds (`linear-gradient(to right, aquamarine, lavenderblush)`).
+
+## Reference
+
+### At-rules
+
+- {{cssxref("@property")}}
+  - [syntax](/en-US/docs/Web/CSS/@property#descriptors) descriptor
+    - [`+` and `#`](/en-US/docs/Web/CSS/@property#descriptors) multipliers
+    - [`|`](/en-US/docs/Web/CSS/@property#descriptors) combinator
+  - [inherits](/en-US/docs/Web/CSS/@property#descriptors) descriptor
+  - [initial-value](/en-US/docs/Web/CSS/@property#descriptors) descriptor
+
+### Interfaces and APIs
+
+- {{domxref('CSSPropertyRule')}}
+- {{domxref('CSS/registerProperty_static', 'CSS.registerProperty()')}}
+
+## Guides
+
+- [Using the CSS properties and values API](/en-US/docs/Web/API/CSS_Properties_and_Values_API/guide)
+  - : Explains how to register custom properties in CSS and JavaScript, with hints on handling undefined and invalid values, fallbacks, and inheritance.
+
+## Related concepts
+
+- {{cssxref("var")}}
+- [CSSRule](/en-US/docs/Web/API/CSSRule)
+- [CSSStyleValue](/en-US/docs/Web/API/CSSStyleValue)
+- [CSS scoping](/en-US/docs/Web/CSS/CSS_scoping)
+- [Using shadow DOM](/en-US/docs/Web/API/Web_components/Using_shadow_DOM)
+- [CSS Typed Object Model API](/en-US/docs/Web/API/CSS_Typed_OM_API)
+- [CSS Painting API](/en-US/docs/Web/API/CSS_Painting_API)
+- [Worklet](/en-US/docs/Web/API/Worklet)
+
+## Specifications
+
+{{Specifications}}
+
+## See also
+
+- [CSS cascade and inheritance](/en-US/docs/Web/CSS/CSS_cascade)
+- [CSS scoping](/en-US/docs/Web/CSS/CSS_scoping) module
+- [Using shadow DOM](/en-US/docs/Web/API/Web_components/Using_shadow_DOM)
+- [CSS Painting API](/en-US/docs/Web/API/CSS_Painting_API) module
+- [Worklet](/en-US/docs/Web/API/Worklet) interface
+- [CSS Houdini](/en-US/docs/Web/Guide/Houdini)
+- [CSS `env()`](Web/CSS/env)
+- [CSS Typed Object Model](/en-US/docs/Web/API/CSS_Typed_OM_API)

files/en-us/web/css/env/index.md

@@ -212,8 +212,8 @@ main {
 ## See also
 
 - {{CSSxRef("var", "var(…)")}}
-- [CSS Custom Properties for Cascading Variables](/en-US/docs/Web/CSS/CSS_cascading_variables)
-- [Custom Properties (--\*)](/en-US/docs/Web/CSS/--*)
+- [CSS custom properties for cascading variables](/en-US/docs/Web/CSS/CSS_cascading_variables) module
+- [Custom properties (`--*`): CSS variables](/en-US/docs/Web/CSS/--*)
 - [Using CSS custom properties (variables)](/en-US/docs/Web/CSS/Using_CSS_custom_properties)
 - [Customize the window controls overlay of your PWA's title bar](https://web.dev/articles/window-controls-overlay)
 - [Display content in the title bar](https://docs.microsoft.com/microsoft-edge/progressive-web-apps-chromium/how-to/window-controls-overlay)

files/en-us/web/css/using_css_custom_properties/index.md

@@ -535,5 +535,6 @@ element.style.setProperty("--my-var", jsVar + 4);
 
 - [Custom property syntax](/en-US/docs/Web/CSS/--*)
 - {{cssxref("@property")}} at-rule
-- [CSS Properties and Values API](/en-US/docs/Web/API/CSS_Properties_and_Values_API)
 - [`var()`](/en-US/docs/Web/CSS/var)
+- [CSS Properties and Values API](/en-US/docs/Web/API/CSS_Properties_and_Values_API)
+- [CSS custom properties for cascading variables](/en-US/docs/Web/CSS/CSS_cascading_variables) module

files/en-us/web/css/var/index.md

@@ -195,5 +195,6 @@ Since `--main-bg-color` isn't set, the body's `background-color` will fall back
 ## See also
 
 - {{cssxref("env","env(…)")}} – read‑only environment variables controlled by the user‑agent.
-- [Using CSS variables](/en-US/docs/Web/CSS/Using_CSS_custom_properties)
+- [Using CSS custom properties (variables)](/en-US/docs/Web/CSS/Using_CSS_custom_properties)
 - {{cssxref("@property")}} at-rule
+- [CSS custom properties for cascading variables](/en-US/docs/Web/CSS/CSS_cascading_variables) module