[csswg-drafts] [css-properties-values-api] enhance `@property` with `scope` for `source`/`local` to determine the scope of nested custom property values (#10178)

brandonmcconnell has just created a new issue for https://github.com/w3c/csswg-drafts:

== [css-properties-values-api] enhance `@property` with `scope` for `source`/`local` to determine the scope of nested custom property values ==
## The Problem / TL;DR

It'd be great to have a way to opt into granular control over the custom property values nested in the definition of other custom properties. This way, if I have one custom property I'm using, `--result`, and `--result` is comprised of some combination of several other custom properties, it would be very helpful to be able to change the value of one of those in the current scope and have that flow into the custom properties "derived" from it in that same scope.

I have encountered this myself a few times and needed a break-glass solution, but the only one was to completely redefine the outer custom property again to "re-jigger" its updated value.

Real-world examples of the issue
* https://x.com/adamwathan/status/1775937299919859961
* https://stackoverflow.com/questions/58206867/overriding-root-css-variables-from-inner-scopes
* https://stackoverflow.com/questions/52015737/css-scoped-custom-property-ignored-when-used-to-calculate-variable-in-outer-scop
* https://stackoverflow.com/questions/48079541/css-variables-inheritance-and-fallback

I propose we create a way to opt into such functionality for custom properties within the `@propeprty` rule.


## Abstract

This proposal presents a new `scope` descriptor to enhance CSS custom property scoping capabilities incorporated within the `@property` rule. This attribute facilitates a more flexible handling of CSS custom properties. It allows fine-grained control on how nested values within a CSS variable can be read: from the source (default and current behavior) or the current local scope. This choice and difference would strongly influence the modularity of a given variable.

## 1. Introduction

Maintaining the structure and comprehension of styling within web applications can pose challenges. The ability to control where a CSS custom property looks to for nested values greatly enhances the flexibility and power of CSS variables. The `scope` descriptor for the `@property` rule is proposed to extend the control for developers over custom properties within their stylesheets.

## 2. `@property` Rule Enhancement for Scope Control

### 2.1 Declaring Scope

- The `@property` rule will introduce a `scope` descriptor that directs where custom properties should read nested values:

```css
@property --shadow {
  scope: source | local;
  syntax: '<color>';
  inherits: true;
  initial-value: 0 4px 8px var(--shadow-color, rgb(0 0 0 / .5));
}
```

### 2.2 Scope Attributes

**Source** (Default): The property reads nested values in its original defined scope.

```css
@property --shadow {
  scope: source;
}
```

**Local:** The property reads nested values in its current local scope.

```css
@property --shadow {
  scope: local;
}
```

## 3. Use Cases

The improved level of control, such as enabling child scopes to redefine nested values that will 'locally' cascade down into other dependent variables provide several benefits:

- **Component-based design:** Local scoping can aid in the isolation and encapsulation of styles within self-contained components.

- **Inheritance & Overriding:** Different components or variations of the same component could conveniently alter base styles according to their specific needs.

- **Theme customization:** Adjusting elements' properties as nested variables within them, facilitating application-level or component-level theme customization.

## 4. Gotchas/Considerations

### 4.1 Compatibility

Consideration must be given to how this new feature will be introduced seamlessly without breaking the existing designs. Also, plan a graceful degradation strategy for browsers that don't support this feature yet.

### 4.2 Clarity over Priority or Precedence

Clear rules or expectations need to be established when both local and source variables are available. The precedence rules should be intuitive for developers to accurately predict which value will be applied.

## 5. Conclusion

The introduction of the `scope` descriptor in the `@property` rule augments the expressiveness and power of CSS, enabling developers to leverage more control over their CSS variables by allowing fine-grained control over the scope of variable values, thereby fostering an increasingly modular approach to styling.

Please view or discuss this issue at https://github.com/w3c/csswg-drafts/issues/10178 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Friday, 5 April 2024 04:02:53 UTC