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

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

@@ -130,3 +130,5 @@ For item three, the `--item-size` value gets set to `1000px`. While `1000px` is
 - [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,134 @@
 ---
-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.
+
+Custom properties are defined using [two dashes (`--`)](/en-US/docs/Web/CSS/--*) and are subject to the [cascade](/en-US/docs/Web/CSS/Cascade), so they inherit their value from their parent.
+The purpose of custom properties is to help manage complex CSS stylesheets by allowing you to define a property's value in one place and reuse that value in multiple declarations across a project.
+A benefit of custom properties is improved readability and semantics.
+For example, `--dark-grey-text` and `--dark-footer` are easier to understand than hexadecimal colors such as `#00ff00`, and the context of their use is much more apparent.
+
+## Custom properties in action
+
+To see how custom properties can be used, move the input slider left to right.
+When the value of the slider changes between 0 and 360, this updates the `--hue` property and color of the boxes inside the grid.
+The `--hue` custom property is used in a slightly different way in each box, and changing the value of `--hue` in one place affects multiple different elements where it's referenced.
+
+```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;
+}
+```
+
+```css
+: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%);
+}
+/* Continued up to color-8 ... */
+```
+
+```css hidden
+#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)}}
 
 ## Reference
 
 ### Properties
 
-- {{cssxref("--*")}}
+- {{cssxref("--*")}} syntax for defining custom properties in CSS.
+
+### Functions
+
+- {{cssxref("var")}} for referencing a custom property's value.
+
+## 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.
+
+## Related concepts
+
+- The [CSS Properties and Values API](/en-US/docs/Web/CSS/CSS_properties_and_values_API) provides additional interfaces for defining custom properties that allow you to set an initial value fir the property, define data type constraints and provide control over inheritance.
+  This specification provides:
+
+  - [CSS @property](/en-US/docs/Web/CSS/@property) at-rule for defining custom properties in CSS.
+  - [CSS.registerProperty()](/en-US/docs/Web/API/CSS/registerProperty_static) method for defining custom properties in JavaScript.
 
 ## Specifications
 
 {{Specifications}}
+
+## See also
+
+- [CSS cascade and inheritance](/en-US/docs/Web/CSS/CSS_cascade)
+- [CSS `env()`](Web/CSS/env)

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

@@ -0,0 +1,88 @@
+---
+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 is is part of the [CSS Houdini](/en-US/docs/Web/Guide/Houdini) umbrella of APIs and allows authors to define custom properties for cascading variables.
+This API expands on [CSS custom properties for cascading variables](Web/CSS/CSS_cascading_variables) which allows authors to define custom properties in CSS using [two dash syntax (`--`)](/en-US/docs/Web/CSS/--*).
+
+The additional functionality provided by the Properties and Values API is the introduction of control over inheritance, the ability to set initial values, and data type constraints.
+Authors can define CSS properties using the [`@property`](/en-US/docs/Web/CSS/@property) at-rule in CSS and the {{domxref('CSS/registerProperty_static', 'CSS.registerProperty')}} interface in JavaScript.
+
+## Properties and Values API in action
+
+Registered properties have an associated data type that the browser can use in different contexts, which makes them a great choice for animations and transitions.
+Using custom properties defined in CSS using the [two dash syntax (`--`)](/en-US/docs/Web/CSS/--*) works more like a string substitution, so a CSS [transition](/en-US/docs/Web/CSS/transition) won't work as expected.
+When you hover over the box below, the background color changes over two seconds with proper interpolation between the different colors.
+
+```js
+CSS.registerProperty({
+  name: "--stop-color",
+  syntax: "<color>",
+  inherits: false,
+  initialValue: "cornflowerblue",
+});
+```
+
+```css hidden
+.box {
+  padding: 1rem;
+  width: 80%;
+  height: 4rem;
+  font-family: sans-serif;
+  color: white;
+  border-radius: 0.5rem;
+}
+```
+
+```css
+.box {
+  --stop-color: cornflowerblue;
+  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)}}
+
+## Reference
+
+### At-rules
+
+- {{cssxref("@property")}}
+
+### Functions
+
+- {{cssxref("var")}}
+
+### Interfaces
+
+- {{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.
+
+## Specifications
+
+{{Specifications}}
+
+## See also
+
+- [CSS cascade and inheritance](/en-US/docs/Web/CSS/CSS_cascade)
+- [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