Define guidelines for preprocessors, libraries, frameworks

[romainmenke]

Guidelines already exist for polyfills : https://www.w3.org/2001/tag/doc/polyfills/
A similar document with considerations and suggestions could be created for CSS preprocessors, libraries, frameworks.
(Any tool can choose to adopt these or not)

The goal of this document would be to prevent conflicts between future CSS features and non-standard things in developer tools.

if this already exists please let me know, I couldn't find it

"preprocessors, libraries, frameworks" will be referred to as "tools".

---

1. In tools it is preferable not to invent new syntax as they are not used in a vacuum.
   Developers also use linters, static analysis and need IDE features (syntax highlighting, auto complete, ...).
   Using existing syntax/grammar with custom keywords makes it much easier to roll out a new feature in one tool, without requiring the whole ecosystem to adapt.

2. tools can move at a much faster pace than the CSS spec and browsers.

3. The most obvious name for a feature is often the best name. (and multiple distinct features can all have the same best name)

4. there is no working group for tooling (that I know of)

These factors make it absolutely certain that conflicts will keep on happening without proper guidelines.

---

Conflicts are not only a burden on the creators and users of preprocessors when tools and source code need to be updated.
Users might have years of experience and knowledge associated with how a certain keyword works.

This is an issue today with PostCSS plugins transforming nested CSS.
Users expect & to behave in a certain way based on experience with Sass and see the specced feature as bugged.

Whereas avoiding conflicts will allow developers to freely mix tooling features and native features.

---

Note :

It is not my intention to have a document that defines how tools must work or what they can or can not implement.

Only to have a safe framework to let tools grow together with native CSS features.

[romainmenke]

Anecdotal evidence of why this would be helpful.

postcss-preset-env aims to follow standard closely but non standard features or implementations slip in for various reasons.

---

The nesting spec plugin was updated to be spec compliant and we have received many reports and questions about this.

It would have been better if a different character was used by us until the spec was more mature :

.foo {
  color: blue;

  🪆:hover {
    color: red;
  }
}

We could have maintained this indefinitely and no one would have had to do any migrations.

---

We also started shipping experimental versions of plugins which solves an internal problem.

But we could have done a bit better here.
A prefixed :has() function would have allowed users to try the feature and get familiar with it. And it would have been safe in case the final implementation in browsers didn't match ours.

.foo:csstools-has(> .bar) {
  color: red;
}

---

We are currently working on a new feature which only makes sense in a preprocessor : csstools/postcss-plugins#304

This itself is a bandaid for non-standard things conflicting with standard features.
Having a future conflict would be unfortunate.

[romainmenke]

Another example of a library clashing with a native feature : #7676 (comment)

This could have been avoided with a jquery specific prefix.
This scenario is exactly what I also described above.

[romainmenke]

More on nesting :

#4748 (comment)

Because we implemented the specced behaviour without any prefix as a PostCSS plugin we made it impossible to gather unbiased feedback about alternatives from stylesheet authors.

[romainmenke]

Because this keeps happening I am reopening this issue.
I still think it would be useful to define guidelines to avoid future conflicts.

I personally would welcome this because I am not an expert on this either and I might be producing future conflicts unknowingly.

[romainmenke]

Another example :

https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-custom-media#readme

A PostCSS plugin for @custom-media that was created even when the specification is way to vague to start implementations.

When checking the plugin for spec compliance I found at least two points that require clarification :

• [mediaqueries-5] Syntax for <media-query> doesn't include <extension-name> for custom media queries #7724
• [mediaqueries-5] Define logical evaluation steps for custom media #7725

[Loirooriol]

Why not use vendor prefixes? :-foo-has(), @-foo-custom-media, etc.

[romainmenke]

For new PostCSS plugins I have indeed adopted a csstools- prefix.
But even within our org (csstools) we lack a guideline for this and plugins are still created that do not have this prefix.

-csstools- as prefix that follows browser vendor prefix standards would also work, but we are not a browser vendor.

This is not a popular choice and the first thing users do is open an issue requesting us to drop this prefix. But it is the right thing to do for the ecosystem.

---

I think the CSS WG is best suited to create general guidelines because it has the most reach and the best insights into these types of issues.

If I create guidelines for the csstools org it only solves issues we create where I would like to see a more general solution.

These guidelines might be little more than : "you must adopt vendor prefixes when inventing features"

[romainmenke]

A vendor prefix guideline does not help for syntactical things like custom units : https://github.com/csstools/custom-units

.my-component {
  font-size: 24--rpx;
  padding-inline: 3--step;
}