[css-properties-values-api] enhance `@property` with `scope` for `source`/`local` to determine the scope of nested custom property values

[brandonmcconnell]

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:

@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.

@property --shadow {
  scope: source;
}

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

@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.

[yisibl]

I think it would be better in combination with @scope.

[brandonmcconnell]

@yisibl Would you mind demonstrating what you're envisioning?

[yisibl]

@scope [(<scope-start>)]? [to (<scope-end>)]? {
  @property --foo {}
} 

[brandonmcconnell]

@yisibl Ah but the primary use case here is for custom properties with nested custom properties in their values to be able to reactively update when those nested properties are updated further down in the cascade/CSSOM.

Using at-property within at-scope might need to be a separate proposal, unless I'm missing the direct correlation. 🙂

[bramus]

Using at-property within at-scope might need to be a separate proposal, unless I'm missing the direct correlation. 🙂

That is a different issue indeed. Some time ago I have filed https://github.com/w3c/csswg-drafts/issues/9077 for what @yisibl is asking, but turns out it is not possible. See https://drafts.css-houdini.org/css-properties-values-api-1/#shadow-dom for an explanation why.