Define "descriptor" and "property" somewhere · Issue #5633 · w3c/csswg-drafts (original) (raw)

As far as I can tell, we don't actually <dfn> "descriptor" or "property" anywhere. We touch on this in Syntax, § 5 Parsing, defining declaration:

Declarations are further categorized as "properties" or "descriptors", with the former typically appearing in qualified rules and the latter appearing in at-rules. (This categorization does not occur at the Syntax level; instead, it is a product of where the declaration appears, and is defined by the respective specifications defining the given rule.)

It's come to my attention that some people who've been around for browsers for a long time don't understand the difference here, and we don't really ever make this super clear.

Looking at CSS Fonts for example: the only explicit clue between https://drafts.csswg.org/css-fonts/#font-family-prop and https://drafts.csswg.org/css-fonts/#font-family-desc is the titles of each section. We say the latter is "For: @font-face", but that's about it, and what exactly "For" means isn't totally clear.

This ends up relevant in places like CSSOM where we talk about "supported CSS properties" but it doesn't cross-reference anything for what a property is!