Semantics of the CSS "Values" section?

[wbamberg]

Our reference docs for CSS properties contain a subsection of “Syntax” that’s called “Values”, which is generally a <dl>. I’m interested in understanding the semantics of this subsection. My hidden agenda here is: could we express this as structured content, so it could be used by third-party applications like editors and devtools?

The simplest case is where the property is one that just accepts a set of keywords, like, say, color-adjust. In cases like this each value is a permissible keyword, that’s also a possible value for the property as a whole. We could also see how exposing this as structured content could be helpful: for example an editor could provide the list of keywords (and associated descriptions) as possible autocompletions.

Outside this simple case things are much less clear. Quite often the “Values” items seem to be CSS data types (e.g. background-color) or higher-level CSS values that are defined in the formal syntax (e.g. border-style or border-left - although in that case it appears as if perhaps the formal syntax is out of sync with the “Values” list).

Often in these cases, the “Values” items are not actually valid values for the property as a whole: they are more like annotations to the formal syntax. So the formal syntax describes the syntax of the whole property value, and the “Values” items explain individual items that appeared in the formal syntax.

In still other cases though, “Values” lists overall syntactical forms (e.g. in the docs for rotate) and seems to be much more free-form (it’s a bit like a human-readable gloss of the formal syntax). grid-template is a similar case, except that this uses sections of the formal syntax as the <dt> items, rather than more free-form text.

So…what do we think the semantics of “Values” is supposed to be? If all the variations listed above are valid, it seems like it doesn’t really have any semantics, it’s just “anything goes”. And that might be a reasonable decision to make about this. That would mean that tools won’t be able to do much with it though.

[chrisdavidmills]

I would say that this is a difficult structure to have a one-size-fits-all solution for that is readable by the target audience, in all cases.

When we’ve got a simple set of values, we are fine.

when we’ve got a simple set of values that are defined under a specific data type (e.g. border-style). We could just present them in exactly the same way, and specify somewhere what data type they are defined in, for the curious.

When we’ve got complex formal syntax it is much more difficult to present this in a way that makes any sense to the user. In the case of background-color, there are a lot of different options, so it seems to make sense to just link to the page, especially given that you’ll be expected to choose just a single one of the presented options for your property value.

In the case of more complex ones like rotate and grid-template, it gets really difficult. Often a valid value is made out of a specific combination of the bits of the formal syntax, which isn’t particularly obvious. This is why I went with human-readable descriptions of the allowable combinations on rotate — I thought listing the formal syntax wouldn’t be helpful. I don’t think the way it is on grid-template is particularly helpful.

Perhaps a sensible way to deal with it would be to list the different property values and value combinations that work (as in, the formal syntax). In situations where the formal syntax is not very obvious, you can optionally include a human-readable description of the value to show instead of the formal syntax, plus a real valid example?

In terms of how this could appear in code editors, I think having a human readable description plus a valid example (or even pseudocode) that is inserted when you select that option and can then edit to what you want, would be quite helpful.