Csswg-drafts: [css-values] Add more examples of author-defined syntax

[tomhodgins]

In [css-values] it includes a section about “Explicitly Author-defined Identifiers” where it explains the naming convention of -- preceding a custom <ident> as the syntax to be used CSS-wide for custom author-defined things.

Presently the only spec that gives an example of using a dashed ident is [css-variables] where it explains the syntax for defining a custom property.

I'm not sure these all belong in the [css-values] spec, but it would be great if there were examples somewhere explaining how to express author-defined syntax in addition to custom properties:

Author-defined At-rules

The syntax for an at-rule is described in [css-syntax] as @ + <ident>, this means an author-defined at-rule would be @ + <dashed-ident> and could take any of the following forms:

@--author-defined;
@--author-defined with prelude;
@--author-defined {}
@--author-defined with prelude {}

Author-defined Psuedo-Class Selectors

The syntax for a pseudo-class selector is described in [selectors] as either : plus either an <ident> or a <function>, and the syntax for an author-defined function is <ident> + (-block, so that means the syntax for an author-defined pseudo-class is : plus either <dashed-ident> or an author-defined <function> (<dashed-ident> + (-block).

:--author-defined {}
:--author-defined() {}

Author-defined Pseudo-Element Selectors

Pseudo-element syntax is also described in [selectors]. The syntax for a pseudo-element in CSS is :: plus either an <ident> or a <function>, so that means the syntax for an author-defined pseudo-element is :: plus either a <dashed-ident> or an author-defined <function> (<dashed-ident> + (-block).

::--author-defined {}
::--author-defined() {}

Author-defined Selector Combinators

The general syntax for a combinator is harder to track down, the idea for /ident/ to represent combinators with names existed at one point in a previous edition of [css-scoping] with the /deep/ combinator (and possibly others) but I'm not sure where in any current specs this naming convention for combinators is described. I believe the way you'd express an author-defined combinator would be / + <dashed-ident> + /.

a /--author-defined/ b {}

Author-defined Functions

Functions are a real workhorse in CSS syntax and a natural extension point for author-defined functionality in many parts of CSS syntax (including in selectors and at-rule preludes). The syntax for a <function> token is shown in [css-syntax] is <ident> + (-block, which would make the syntax for an author-defined function <dashed-ident> + (-block.

a {
  width: --author-defined();
}

Author-defined Units

The <dimension> token which associates a number with a named unit is described in [css-syntax] as the pairing of a <number> with an <ident>, like 5px, this means a <dimension> token with an author-defined unit would be <number> plus a <dashed-ident>:

a {
  width: 1--author-defined;
}

Author-defined Keywords

These are not to be confused with CSS custom properties or var() as keywords are used many places in CSS where properties or values of properties cannot be defined or used. A purely author-defined keyword might simply be a <dashed-ident>:

a {
  width: --author-defined;
}

Author-defined Annotations

I'm not sure if the kind of thing of which !important is the only specified value is called a 'priority' in for !anything-like-this or if 'priority' refers to the important part of !important, so I'll use the placeholder term 'annotation' here. The syntax for !important is described in [css-syntax] as ! plus optional whitespace, plus the literal <ident> important, plus optional whitespace. If there was ever an author-defined annotation like this would the syntax be ! with optional whitespace, a <dashed-ident>, followed by optional whitespace?

a {
  width: 50px !--author-defined;
}

---

I also have a repository with examples of all of these parts of author-defined CSS syntax here: https://github.com/tomhodgins/custom-css

[tabatkins]

I think it would confuse more than it would help to have examples of things that don't yet exist in CSS at all. The only one of your categories that exists so far is author-defined keywords (via the @color-profile rule), which I'd be glad to add in.

[astearns]

That and a custom property example. The mention and link in the note is good. A syntax example would be even better.

[tomhodgins]

As it stands right now, people wanting to extend CSS to include a new at-rule (for example) may not be aware of the <dashed-ident> convention for explicitly author-defined things in CSS and that it's best practice for them to use it, because they have only ever seen <dashed-ident> shown for --custom-properties to date.

I think a lot of people would end up dangerously extending CSS with something like @custom which camps on the platform namespace and limits future CSS specification, so I feel like there should be a warning note included somewhere as well.

The HTML spec does this warning well in the section about creating your own custom data-* attributes. It explains that data-custom="" is valid, but data-library-custom="" is even better since you can tell data-library1-custom apart from data-library2-custom giving the people working with it the most flexibility.

JavaScript libraries may use the custom data attributes, as they are considered to be part of the page on which they are used. Authors of libraries that are reused by many authors are encouraged to include their name in the attribute names, to reduce the risk of clashes. Where it makes sense, library authors are also encouraged to make the exact name used in the attribute names customizable, so that libraries whose authors unknowingly picked the same name can be used on the same page, and so that multiple versions of a particular library can be used on the same page even when those versions are not mutually compatible.

For example, a library called "DoQuery" could use attribute names like data-doquery-range, and a library called "jJo" could use attributes names like data-jjo-range. The jJo library could also provide an API to set which prefix to use (e.g. J.setDataPrefix('j2'), making the attributes have names like data-j2-range).

The same guidance seems to apply to any of the explicitly author-defined parts of CSS as well, @custom should be avoided (though it's valid syntax, it's not safe for authors to use), @--custom is better because it's valid and safe for authors to define themselves forever, and @--library-custom is an even better idea today for flexibility in the future.

Even before there are CSSOM companions to provide official support for defining what these custom things in CSS might do in browser, people are already writing CSS that includes custom author-defined features in it every day, but there's presently no place for them to read and understand how to do it safely the CSS way, and what those best practices are so they don't make a mess (like smooshgate, <modal>, etc) in the meantime.

[tabatkins]

Reasonable, I'll draft something up.

[bkardell]

while my email suggesting a single rule/decision on these from like 2014 or whatever listed most of these example and their seeming relationship to vendor prefixes, keywords and annotations are thing I will admit I never thought of - probably because I don't think there are examples of vendor prefixes anyone has shipped for these... Out of curiosity... Are there?

[tabatkins]

We stopped recommending vendor prefixes several years ago, and outside of WebKit have stopped using them among the major browsers, so no.

[tomhodgins]

Thanks @tabatkins, that new note in [css-values] sounds really good!