Applied review comments

Author: tursunova

css-values-5/if-explainer.md

@@ -4,33 +4,48 @@ This document is an explainer for the `if()` function proposed for CSS Values an
 
 ## Introduction
 
-The `if()` function introduces powerful, inline conditional logic to CSS properties. It allows authors to select a value for a property based on a set of ordered conditions, similar to `if/else` constructs in many programming languages. This provides a more dynamic and streamlined way to write CSS without relying on verbose selectors or JavaScript.
+The `if()` function introduces powerful,
+inline conditional logic to CSS properties.
+It allows authors to select a value for a property based on a set of ordered conditions,
+similar to `if/else` constructs in many programming languages.
+This provides a more dynamic and streamlined way to write CSS
+without relying on verbose selectors or JavaScript.
 
 ## Motivation
 
-Currently, CSS authors often need to repeat selectors to apply different styles under different conditions. For example, to change a property based on a media query, one would write:
+Currently, CSS authors often need to repeat selectors
+to apply different styles under different conditions.
+For example, to change a property based on a custom property for theming,
+one would write:
 
 ```css
 .my-element {
-  color: blue;
+  color: blue; /* default */
 }
 
-@media (min-width: 600px) {
-  .my-element {
-    color: red;
-  }
+.theme-dark .my-element {
+  color: red; /* theme override */
 }
 ```
 
-While functional, this pattern can lead to verbose and fragmented code, especially when multiple conditions are involved. The `if()` function aims to simplify this by allowing conditional logic to be expressed inline within a single declaration:
+While functional, this pattern can lead to verbose and fragmented code,
+especially when multiple conditions are involved.
+The `if()` function aims to simplify this
+by allowing conditional logic to be expressed inline within a single declaration,
+using `style()` query to check custom properties values:
 
 ```css
+/* Assuming a parent has --theme: dark set */
 .my-element {
-  color: if(media(min-width: 600px): red; else: blue);
+  color: if(style(--theme: dark): red; else: blue);
 }
 ```
 
-This approach improves readability and co-locates related logic, making stylesheets easier to maintain. This is especially powerful when combined with CSS Custom Properties, allowing for the creation of dynamic, themeable components with logic encapsulated directly in the CSS.
+This approach improves readability and co-locates related logic,
+making stylesheets easier to maintain.
+This is especially powerful when combined with CSS Custom Properties,
+allowing for the creation of dynamic,
+themeable components with logic encapsulated directly in the CSS.
 
 ## Syntax
 
@@ -46,21 +61,17 @@ The `if()` function's syntax is formally defined as:
   style( <style-query> )
 ```
 
-In essence, the function is a list of conditional branches separated by semicolons. Each branch contains a condition followed by a colon (`:`) and a value. The conditions are evaluated in order, and the value from the first branch with a true condition is used.
+In essence,
+the function is a list of conditional branches separated by semicolons.
+Each branch contains a condition followed by a colon (`:`) and a value.
+The conditions are evaluated in order,
+and the value from the first branch with a true condition is used.
 
-The `else` keyword can be used as a condition that is always true. This makes it useful for providing a final fallback value, as any branches after an `else` branch will be ignored.
+The `else` keyword can be used as a condition that is always true.
+This makes it useful for providing a final fallback value,
+as any branches after an `else` branch will be ignored.
 
-## Core Use Cases
-
-The `if()` function is well-suited for a variety of scenarios where a property's value needs to change based on context.
-
-*   **Responsive Design:** Instead of defining multiple rules in separate `@media` blocks, `if()` allows responsive logic to be encapsulated within a single property. This is ideal for component-based architectures, as it co-locates the logic and makes it easier to manage fluid typography, spacing, or layout adjustments directly where they are applied.
-
-*   **Theming:** `if()` enables dynamic and sophisticated theming systems. By checking the value of a custom property with `style()`, a component can adjust multiple aspects of its appearance (e.g., background, text color, border) based on a single theme flag (like `--theme: dark`). This centralizes theme logic and allows for the creation of derived styles that automatically respond to theme changes.
-
-*   **Feature Detection & Progressive Enhancement:** Similar to the `@supports` rule, `if()` can check for browser feature support. Its advantage is providing an inline fallback within a single declaration. This is perfect for progressively enhancing a component. For example, you can use a modern layout mode like `subgrid` if it's supported, and fall back to a simpler, more widely-supported value like `grid` or `block` if it's not, all within the same `display` property.
-
-## Examples
+## Use Cases
 
 ### 1. Simple Media Query
 
@@ -74,17 +85,33 @@ A common use case is to switch a value based on a media query.
 
 ### 2. Feature Support
 
-Conditionally apply a value based on whether the browser supports a particular CSS feature.
+Conditionally apply a value based on whether the browser supports a particular CSS feature,
+allowing for progressive enhancement.
+For example, using a modern,
+more vibrant color from a wider-gamut color space like Display P3,
+inside of a gradient,
+and falling back to a standard sRGB color if P3 is not supported.
+Without `if()`,
+the author would have to repeat the entire `linear-gradient()` expression.
 
 ```css
-.card {
-  display: if(supports(display: grid): grid; else: block);
+.highlight {
+  background-image: linear-gradient(
+    to right,
+    hsl(50 100% 50%),
+    if(
+      supports(color: color(display-p3 0 0 0)): color(display-p3 1 0.5 0);
+      else: hsl(30 100% 50%)
+    )
+  );
 }
 ```
 
 ### 3. Theming with Custom Properties
 
-The `if()` function is particularly powerful for creating themes. Here, we use `style()` to check the value of a `--theme` custom property inherited from an ancestor and adjust colors accordingly.
+The `if()` function is particularly powerful for creating themes.
+Here, we use `style()` to check the value of a `--theme` custom property inherited from an ancestor
+and adjust colors accordingly.
 
 ```css
 /* On a parent element, you might have: --theme: dark; */
@@ -108,24 +135,30 @@ The `if()` function is particularly powerful for creating themes. Here, we use `
 
 ### 4. Combining Conditions with `and`
 
-Conditions can be combined with boolean keywords like `and`, `or`, and `not`. This allows for more complex logic, such as applying a style only when multiple conditions are met.
+Conditions can be combined with boolean keywords like `and`, `or`, and `not`.
+This allows for more complex logic,
+such as applying a style only when multiple conditions are met.
 
 ```css
 .widget {
   --base-size: 2rem;
   --enhanced-size: 3rem;
 
-  /* Use the enhanced size only on wide screens that also support subgrid */
+  /* Use the enhanced size only on wide screens that also support flexbox */
   font-size: if(
-    media(width >= 1024px) and supports(display: subgrid): var(--enhanced-size);
+    media(width >= 1024px) and supports(display: flex): var(--enhanced-size);
     else: var(--base-size)
   );
 }
 ```
 
 ## Fallback Behavior
 
-If no condition in an `if()` function evaluates to true and no `else` branch is provided, the function resolves to an empty token stream. This makes the declaration invalid at computed-value time, causing the property to fall back to its inherited or initial value (behaving like `unset`).
+If no condition in an `if()` function evaluates to true
+and no `else` branch is provided,
+the function resolves to a `<guaranteed-invalid>` value.
+This makes the declaration invalid at computed-value time,
+causing the property to fall back to its inherited or initial value (behaving like `unset`).
 
 ```css
 .box {
@@ -136,6 +169,18 @@ If no condition in an `if()` function evaluates to true and no `else` branch is
 
 To ensure predictable behavior, it is recommended to always provide an `else` branch.
 
+## Stakeholder Feedback
+
+This proposal has been discussed in the CSS Working Group,
+and feedback from browser vendors and web developers has been positive.
+Currently, `media()`, `supports()`, and `style()` queries are supported,
+but there are possibilities for expansion in the future.
+
 ## Security and Privacy Considerations
 
-The `if()` function itself does not introduce new security or privacy concerns. It provides a new syntax for expressing conditional logic but relies on existing mechanisms (`media()`, `supports()`, `style()`) that have their own, already-defined security profiles. It does not introduce any new capabilities that could be used to fingerprint users or exfiltrate data.
+The `if()` function itself does not introduce new security or privacy concerns.
+It provides a new syntax for expressing conditional logic
+but relies on existing mechanisms (`media()`, `supports()`, `style()`)
+that have their own, already-defined security profiles.
+It does not introduce any new capabilities
+that could be used to fingerprint users or exfiltrate data.