CSS Cascade Control

1. Introduction

A number of CSS properties are list-valued (background, transition, etc) or set-valued (will-change, etc). These can be difficult to manage in an application written by several authors (or partially styled by indepedent libraries), or even when there’s only a single author that just wants to style an element in multiple independent ways.

For example, a particular class might do some transform work, and thus want to set will-change: transform, while another class does some opacity changes, and thus wants to set will-change: opacity. Done naively, if these two classes get set at the same time, one will win over the other, and will-change will only reflect one of the values.

Currently, the only way to get around this is to explicitly handle the collision, manually applying will-change: transform, opacity when the element matches both classes. This sort of explicit collision-handling is unmaintainable, and can quickly grow out of control if more cases are added, as each one increases the number of combinations to be handled combinatorially. (A third class means you need to explicitly handle the 1+2, 1+3, 2+3, and 1+2+3 cases. A fourth class means handling 11 different combinations!)

In this spec we propose a few possible mechanisms to handle these situations more elegantly.

2. Cascade Declarations

During the cascade process, multiple declarations of the same property on a given element are sorted in specificity order to produce the output of the cascade, and then only the last value (the one with highest specificity) is actually used as the value of that property on the element.

A cascade modifier is a modifier on a property name that makes the property’s value depend partially on the previous cascaded value: the value for that property that comes before the current value (that is, is lower specificity) in the output of the cascade.

For any set-valued property with a name set-prop, the following cascade modifiers exist:

set-prop+

Represents the union of its value with the previous cascaded value.

set-prop-

Represents the difference of the previous cascaded value with its value. (That is, the previous cascaded value, minus the current values.)

set-prop{}

Represents the intersection its value with the previous cascaded value.

This involves defining the "unit" of each set-valued property (for example, in will-change each keyword is a "unit"), and ensuring that all of them have a "null" value (like none).

For any list-valued property with a name list-prop, the following cascade modifiers exist:

list-prop+

Represents the current value appended to the end of the previous cascaded value.

+list-prop

Represents the current value prepended to the start of the previous cascade value.

The "unit" of list-valued properties are much easier to define; for all but some legacy properties like counter-reset, it’s just splitting on commas.

.foo {
  box-shadow+: 2px 2px;
}
.foo {
  box-shadow+: blue;
}

2.1. Managing Order Explicitly with Variables

Using cascade modifiers directly can achieve a number of useful, simple effects, but direct usage doesn’t allow a number of common use-cases. For example, you can’t override a particular cascade modifier with a more specific rule.

div {
  background-image: url(base.jpg);
}
div.foo {
  +background-image: url(one.jpg);
}
div.foo.bar {
  +background-image: url(two.jpg);
}

The preferred pattern to achieve this is to use a custom property:

div {
  background-image: url(base.jpg);
  +background-image: var(--upper-background) !important;
}
div.foo {
  --upper-background: url(one.jpg);
}
div.foo.bar {
  --upper-background: url(two.jpg);
}

div {
  background-image: var(--upper-background, none), url(base.jpg);
}
div.foo {
  --upper-background: url(one.jpg);
}
div.foo.bar {
  --upper-background: url(two.jpg);
}

3. cascade() Function