Csswg-drafts: [css-variables] Documentation needed on using variables with JavaScript

[HeidiEkenstam]

https://drafts.csswg.org/css-variables/
It might be helpful to have some documentation on how to use variables with JavaScript.

[Loirooriol]

This is defined in CSSOM, and CSS Variables already has this reminder in §4. APIs:

Note: Custom properties do not appear on a CSSStyleDeclaration object in camel-cased form, because their names may have both upper and lower case letters which indicate distinct custom properties. The sort of text transformation that automatic camel-casing performs is incompatible with this. They can still be accessed by their proper name via getPropertyValue()/etc.

[AmeliaBR]

It's more than just not having camel-casing.

My first instinct would be to use element.style["--my-var"], but that doesn't work either: there are no getter/setters in current browsers. You need to use element.style.getPropertyValue("--my-var") and so on. Which almost no one uses in JS code on the web, so many developers don't even know those methods exist.

I _assume_ that if you're using Houdini to register custom properties, then the object-notation getters & setters would work. But there's nothing specifically about that in any spec.

Regardless, I agree that the note in the current spec could be a lot more useful. This is a big stumbling block for devs just starting to experiment with custom properties as variables.

[tabatkins]

The .gPV() thing is already noted in the spec, as @Loirooriol points out.

I assume that if you're using Houdini to register custom properties, then the object-notation getters & setters would work

I'm not expecting it to. That would involve changing the set of attributes on an object on the fly, which I don't think has precedent.

[HeidiEkenstam]

This information is available online from various sources, but they all do things a little differently and I still see people post questions due to confusion. I noticed that there wasn't straightforward documentation on this topic from the source, so I figured it would be worth mentioning. For the most part I’m talking about how to get and set property values.

[LeaVerou]

This is defined in CSSOM, and CSS Variables already has this reminder in §4. APIs:

This raises a good point: Often information needed to understand a spec is scattered across multiple specs. Here it's done manually, but what if Bikeshed treated references to specs in the same way Github treats references to issues, where they are bidirectional by design: If you reference issue B from issue A, issue B also gets a reference to issue A. Therefore, since CSSOM is referencing Custom Properties, Custom Properties could get a reference to that part of the CSSOM spec. What do you think, @tabatkins?

[plinss]

I believe there are plans for bi-directional links already in the works. I need to augment Shepherd's spec parser to track outbound links as well as anchors so Bikeshed would have the data it needs to do this. I won't be able to get to it until after the f2f though.