[css-properties-values-api] Providing a way for @property to be opinionated about its usage

[JamesIves]

https://drafts.css-houdini.org/css-properties-values-api-1/#custom-property-registration

I've been using the @property syntax over the last few weeks and to this point I've found it quite useful. I keep however finding myself wondering if it could be even more robust.

In a design system, it's common for specific properties to be used for strictly for certain purposes, for example, you might have a --background-primary value which is used specifically for backgrounds, likewise for things such as spacing, --space-xl could be intended for margin or padding values, but it may not be intended to be used for font sizes despite there being overlap in the value type.

Take the following example, this color can be universally used:

@property --color-surface-primary {
  syntax: '<color>';
  inherits: false;
  initial-value: #ff0000;
}

Having a way to provide a list of valid use cases would make this much more self-documenting to the consumer while making things less error-prone. In the following example I've added a valid-properties key that corresponds with the CSS properties the defined variable can be used in:

@property --color-surface-primary {
  syntax: '<color>';
  inherits: false;
  initial-value: #ff0000;
  
  valid-properties: 'background-color'
}

If you wanted it valid for multiple use cases, a list could be provided. If a @property is incorrectly used, it could fall back to whatever the default value is.

@property --color-surface-primary {
  syntax: '<color>';
  inherits: false;
  initial-value: #ff0000;

  valid-properties: 'background-color, color'
}

Enforcing specific properties may be somewhat too cumbersome, but some degree of grouping may be better similar to how Figma handles variable scoping, where you can selectively restrict how a variable is used across a design file.

Something like this, would allow design systems to be more opinionated about the usage of the properties they provide by enforcing that they are used in the intended ways. This would make things much more adjacent to type-safety checks in TypeScript which would be awesome.

First time making a suggestion here. Please go easy on me, apologies if this has been talked about before. 😂