Establish a Core CSS deprecation path

[isabel_brison]

Problem: Core CSS is a public API, and gets used as such by plugins. This means that when a selector is no longer used in wp-admin, deleting any related CSS rules can still break third party code. However, the cautious approach of not deleting any CSS leads to bloated files, with a negative impact on performance.

Solution: define a clear deprecation path for Core CSS, announcing in advance when any selector and related rules are being deprecated. This allows third parties to update their code in a timely manner.

What will this look like in practice? As discussed in the CSS meeting: ​https://make.wordpress.org/core/2021/04/13/css-chat-summary-08-april-2021/,

• When a selector is no longer used in Core, move related CSS to a deprecated.css file.
• This file can be optionally enqueued by plugins that require any of its CSS.
• Deprecation is announced in the release dev notes.
• Linters and other automated tools can help enforce non-use of deprecated selectors.

[audrasjb]

Hello there,

That's a nice idea.

But I have a dummy question :)
My concern is about the way we should handle deprecation history for a given CSS selector (or CSS rule).

Let's say, for example we have this in WP 5.7:

/** CSS File: example.css */
.example {
    font-size: 1em;
}

In WP 5.8 we decide to change the font size, and we start to maintain the deprecated.css file:

/** CSS File: example.css */
.example {
    font-size: 1.5em;
}
/** CSS File: deprecated.css */
.example {
    font-size: 1em; // @deprecated 5.8.0
}

Finally that was a bad idea, so in WP 5.9, we need to use a different font size again:

/** CSS File: example.css */
.example {
    font-size: 2em;
}
/** CSS File: deprecated.css */
.example {
    font-size: [what's the best value here? 1em or 1.5em???]; // @deprecated 5.9.0
}

Should we only maintain the last major release's version of each CSS rule or declaration?

[johnjamesjacoby]

with a negative impact on performance

Is the negative performance impact of unused CSS being enqueued a bigger problem than the negative experience plugin users will have when they see a broken WordPress admin interface because of an unenqueued deprecated.css? 🧐

In my opinion, no. Any potential UI breakage is too high of a risk. 🪂

The deprecated.css approach is a problem, in that it will just end up always being enqueued by plugins forever. The bytes saved across the web will be miniscule. The only time anyone will notice is when it's broken.

This is why deprecated.php, ms-deprecated.php, and pluggable-deprecated.php are always included. They exist only for developer and contributor joy; where unused functions go to be forgotten about, but their overhead is forever part of WordPress.

---

CSS is somewhat different in that no promises are ever made to plugin authors that they can rely on it working perfectly forever. When I'm using the built-in WordPress CSS classes, it's because I want to inherit that styling and do not want to invent my own. If it changes, I want those changes. If it's being completely removed, that is a problem that deprecated.css doesn't solve for me as a plugin author because I still need to stay ahead of the WordPress release curve to add support for whatever the new thing is to avoid breakage for my users. And who's to say the old CSS won't break the new CSS?

I'd almost rather the CSS break entirely than walk the line, like the MP6 initiative did. Either you're with it, or you're not.

My vision for solving this problem is one that simply uses the existing enqueue API. New styles get newer, better, more organized CSS in whatever atomic files make sense, and old styles just stay what they are. If a plugin wants to enqueue the new thing, it does. If it wants to keep using the old thing, it can.

Enqueue wp-admin-list-tables-v1 and get the correct CSS for list tables version 1. Componentize and version everything: buttons, forms, settings, etc... when I'm ready to support version 2, I enqueue the new hotness. 🔥

It used to work a lot like this, but over time everything drifted apart and got commingled together a few times. Add into that, the modern desire to slim the CSS down with JavaScript, is in conflict with the convenience of having everything partitioned and readily available and enqueued via PHP.

As a PHP developer, I want to announce to WordPress the core CSS my plugin needs loaded, and that's it. I'm contradicting myself here, but if I can't do that or if the reliability of that is diminished, what will happen is plugins will all start rolling everything out on their own, and there simply will no longer be a "native looking WordPress plugin" because the core CSS cannot be trusted to do its job. (Many plugins are already going this route, and I think it's ultimately a worse experience for everyone - more work, more to learn, more confused users, less familiar UI everywhere.)

[isabel_brison]

I probably should have made it clearer in the description: CSS rules should only be deprecated when the selectors they are attached to are no longer used in Core.

If plugins want to continue using those classnames/ids and whatever CSS is attached to them, they have the option of enqueuing the deprecated.css file. By that point whatever UI the plugin is providing will have styling inconsistencies with Core anyway, so the best route for plugin authors is always to update their UI to use whatever new classes Core is using.

Does that answer your question, @audrasjb ?

[ryelle]

Linking this ​CSS terminology reference, just to have a shared understanding of ruleset/selector/declarations etc - I know I get the terms mixed up sometimes :)

---

I was looking through common.css, and found quite a few instances of selector deprecation — we removed the add-new-h2 class in favor of page-title-action, but need to keep the style on both. Would we split this up and duplicate the CSS into deprecated.css?

.wrap .add-new-h2, /* deprecated */
.wrap .add-new-h2:active, /* deprecated */
.wrap .page-title-action,
.wrap .page-title-action:active {
	margin-left: 4px;
	padding: 4px 8px;
	position: relative;

Other parts of this file are easier to think about, like here, where an entire ruleset is deprecated.

/* Back-compat for plugins. Deprecated. Use .wp-clearfix instead. */
.nav-tab-wrapper:not(.wp-clearfix):after {
	content: "";
	display: table;
	clear: both;
}

---

I think the deprecated file is a good way to iteratively move forward - a way to improve the CSS without an entire redesign. It would need to always be enqueued though, to support the plugins that haven't been updated. So it won't really save any performance.

When would we remove CSS from deprecated.css?

We should also offer some tooling to plugin developers - like a stylelint config to run while building, or javascript that can be run on the site to highlight when deprecated selectors are used. That could help with the reduction of deprecated styles.

[isabel_brison]

I think the deprecated file is a good way to iteratively move forward - a way to improve the CSS without an entire redesign. It would need to always be enqueued though, to support the plugins that haven't been updated.

Hmmm, my thought when suggesting this was that the main advantage would be performance gains from serving less code. If that's not going to happen, there's not a huge point in extracting deprecated CSS to another file - we could just move it to a "Deprecated" section at the bottom of its current file. That will provide pretty much the same DX improvement as a separate file, with a lot less work on our side :)

[ryelle]

In the PR for #54489, I tried a pass at specifically marking things deprecated (and why). For example,

/* @deprecated 5.9.0 -- Button removed from panel. */
.wp-core-ui .welcome-panel .button.button-hero {
...

You can see more deprecated comments ​in the PR itself, the new markup is much simpler so it cuts down a lot of CSS. I went with this format because it can eventually be read by a script, with the version and description separated with double hyphen (inspired by ​stylelint's ignore comments).

I'm not totally sure how it could be used just yet, but I think setting up a format like this would be a good start. Even if it never ends up scripted, at least having a note about what CSS is still relevant is useful.