Re: [csswg-drafts] [css-values] Add more examples of author-defined syntax (#5438)

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](https://html.spec.whatwg.org/multipage/dom.html#embedding-custom-non-visible-data-with-the-data-*-attributes:custom-data-attribute-4) 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.

-- 
GitHub Notification of comment by tomhodgins
Please view or discuss this issue at https://github.com/w3c/csswg-drafts/issues/5438#issuecomment-674995874 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Monday, 17 August 2020 16:58:13 UTC