CSS Custom Functions and Mixins Module Level 1

1. Introduction

This section is not normative.

Note: At this time, this specification only defines custom functions, which operate at the level of CSS values. It is expected that it will define "mixins" later, which are functions that operate at the style rule level.

Custom properties give authors a lot of power to define useful, sometimes complex values in one place, and then re-use them across their stylesheet. They can vary across the document, or based on Media Queries or other conditionals, making them very flexible and responsive.

However, their values are fixed at the point they’re defined, unable to be changed except by fully overriding their previous definition: a --shadow: 2px 2px var(--shadow-color) declaration takes its --shadow-color value from the element it’s declared on, and later changes to --shadow-color on descendant elements don’t alter the value of --shadow for them; they continue to use the shadow color defined where --shadow was defined. This is a common source of confusion for authors making heavy use of composite variables like this.

Custom functions allow authors the same power as custom properties, but parameterized: they have the same flexibility and conditionality as a custom property definition, but take values from other custom properties (or explicitly as arguments) at the point of use. For example, instead of a --shadow custom property, a --shadow() custom function could be defined instead, like:

@function --shadow(--shadow-color <color> : inherit) {
  /* If --shadow-color argument isn't passed,
     or doesn't successfully parse as a <color>,
     try to use the --shadow-color *property*
     from the element instead */

  /* var(--shadow-color) refers to the --shadow-color parameter,
     rather than a custom property,
     but can still use a fallback value as normal */
  result: 2px 2px var(--shadow-color, black);
}

.foo {
  --shadow-color: blue;
  box-shadow: --shadow(); /* produces a blue shadow */
  /* or just */
  box-shadow: --shadow(blue);
}

2. Defining Custom Functions

A custom function can be thought of as an advanced custom property, which instead of being substituted by a single fixed value, computes its substitution value based on function parameters and the value of custom properties at the point it’s invoked. Rather than the var() syntax that custom properties use for substitution, custom functions are invoked by <dashed-function> syntax, allowing additional values to be passed as arguments.

@function --negative(--value) {
  result: calc(-1 * var(--value));
}

html {
  --gap: 1em;
  padding: --negative(var(--gap));
  /* or by passing the value explicitly, like: */
  padding: --negative(1em);
}

<dashed-function>s are arbitrary substitution functions, like var(). Their presence in a property’s value causes it to be assumed valid at parse time, and only evaluated and parsed at computed-value time, after arbitrary substitution has occurred.

2.1. The @function Rule

The @function rule defines a custom function, and consists of a name, a list of parameters, a function body, and optionally a return type described by a syntax definition.

Each function parameter consists of a name (<custom-property-name>); optionally a parameter type, described by a syntax definition; and optionally a default value.

<@function> = @function <function-token> <function-parameter>#? )
  [ returns <css-type> ]?
{
  <declaration-rule-list>
}

<function-parameter> = <custom-property-name> <css-type>? [ : <default-value> ]?
<css-type> = <syntax-component> | <type()>
<default-value> = <declaration-value>
<type()> = type( <syntax> )

If a default value and a parameter type are both provided, then the default value must parse successfully according to that parameter type’s syntax. Otherwise, the @function rule is invalid.

2.1.1. The Function Prelude

The <function-token> production must start with two dashes (U+002D HYPHEN-MINUS), similar to <dashed-ident>, or else the definition is invalid.

The name of the resulting custom function is given by the name of the <function-token>. The optional function parameters are given by the <function-parameter> values (defaulting to an empty set), and the optional return type is given by the <css-type> following the returns keyword (defaulting to type(*)).

@function --foo(--a <length>) { /* ... */ }
@function --foo(--a <color>) { /* ... */ }
@function --foo(--a <length>+) { /* ... */ }

@function --foo(--a type(<number> | <percentage>)) { /* ... */ }

The name of a @function rule is a tree-scoped name. If more than one @function exists for a given name, then the rule in the stronger cascade layer wins, and rules defined later win within the same layer.

If the function parameters contain the same <custom-property-name> more than once, then the @function rule is invalid.

2.1.2. The Function Body

The body of a @function rule accepts conditional group rules, such as @media. Additionally, it accepts the following descriptors:

• The result descriptor, which determines the result of evaluating the function. If no result descriptor exists, the function is valid, but always returns the guaranteed-invalid value.

• Custom properties, providing local variables.

Unknown descriptors are invalid and ignored, but do not make the @function rule itself invalid.

2.2. The result Descriptor

The result descriptor defines the result of evaluating the custom function defined by its @function rule. Using var() functions, it can reference function parameters, local variables, as well as other custom functions via <dashed-function>s.

The result descriptor itself does not have a type, but its resolved value is type-checked during the substitution of a <dashed-function>.

2.3. Arguments & Local Variables

This section is non-normative.

Within a custom function’s function body, the var() function can access local variables (the custom properties defined in the function body), function parameters (the values passed to the function, or set to default values), and custom properties defined at the call site (an element, or another custom function).

In that list, earlier things "win" over later things of the same name—​if you have a local variable named --foo, var(--foo) will be substituted by that local variable, not by an argument or a custom property defined outside. The other values can still be accessed, however: setting the --foo local variable to initial will resolve it to the --foo parameter, while inherit will resolve it to the --foo custom property from the call site.

@function --outer(--outer-arg) {
  --outer-local: 2;
  result: --inner();
}
@function --inner() returns <number> {
  result: calc(var(--outer-arg) + var(--outer-local));
}
div {
  z-index: --outer(1); /* 3 */
}

@function --double-z() returns <number> {
  result: calc(var(--z) * 2);
}
div {
  --z: 3;
  z-index: --double-z(); /* 6 */
}

@function --add-a-b-c(--b, --c) {
  --c: 300;
  result: calc(var(--a) + var(--b) + var(--c));
  /* uses the --a from the call site's custom property,
     the --b from the function parameter,
     and the --c from the local variable */
}
div {
  --a: 1;
  --b: 2;
  --c: 3;
  z-index: --add-a-b-c(20, 30); /* 321 */
}

3. Using Custom Functions

Similar to how the value of a custom property can be substituted into the value of another property with var(), the result of a custom function evaluation can be substituted into the value of a property with a <dashed-function>.

A <dashed-function> is a functional notation whose function name starts with two dashes (U+002D HYPHEN-MINUS). Its argument grammar is:

<dashed-function> = --*( <declaration-value>#? )

A <dashed-function> can only be used where var() is allowed.

If a property contains one or more <dashed-function>s, the entire property’s grammar must be assumed to be valid at parse time. At computed-value time, every <dashed-function> must be replaced before finally being checked against the property’s grammar.

Note: Within the body of a custom function, var() functions might resolve differently than on the element the <dashed-function> is used on. See § 3.1 Evaluating Custom Functions.

A <dashed-function> is evaluated in some context: either in a property value on an element (or in a descriptor that is eventually treated like a property on an element, such as in @keyframes), or in a descriptor in the function body of another custom function that is being applied to a "hypothetical" element. Either way, this provides a calling context, which contains the property or descriptor name containing the <dashed-function>, and the element (or "hypothetical" element) that property/descriptor is being applied to.

As calling contexts are nested by <dashed-function> evaluations inside of custom functions, a calling context’s root element is the real element at the root of the calling context stack.

@function --max-plus-x(--list, --x) {
  result: calc(max(var(--list)) + var(--x));
}
div {
  width: --max-plus-x({ 1px, 7px, 2px }, 3px); /* 10px */
}

@function --foo(--x) {
  result: --foo(10);
}

@function --bar() {
  --x: --bar();
  result: 1;
}

@function --baz(--x) {
  @media (unknown-feature) {
    result: --baz(42);
  }
  result: 1;
}

@function --baz(--x) {
  --y: 10px;
  result: calc(var(--x) + var(--y));
}

div {
  --x: --baz(1px);
  --y: --baz(2px);
  width: var(--x);  /* 11px */
  height: var(--y); /* 12px */
}

3.1. Evaluating Custom Functions

Custom functions are evaluated by, essentially, pretending their function body is a style rule being applied to a hypothetical element, resolving styles as normal, and then returning the value of the result descriptor on that hypothetical element. The hypothetical element "inherits" the values of all custom properties as if it were a child of its calling context, with its function parameters overriding "inherited" custom properties of the same name.

4. Execution Model of Custom Functions

Like the rest of CSS, custom functions adhere to a declarative model.

The local variable descriptors and result descriptor can appear in any order, and may be provided multiple times. If this happens, then declarations appearing later win over earlier ones.

@function --mypi() {
  result: 3;
  result: 3.14;
}

@function --circle-area(--r) {
  result: calc(pi * var(--r2));
  --r2: var(--r) * var(--r);
}

4.1. Conditional Rules

A conditional group rule that appears within a @function becomes a nested group rule, with the additional restriction that only descriptors allowed within @function are allowed within the nested group rule.

Conditional group rules within @function are processed as normal, acting as if the contents of the rule were present at the conditional group rule’s location when the condition is true, or acting as if nothing exists at that location otherwise.

@function --suitable-font-size() {
  result: 16px;
  @media (width > 1000px) {
    result: 20px;
  }
}

@function --suitable-font-size() {
  @media (width > 1000px) {
    result: 20px;
  }
  result: 16px;
}

@function --suitable-font-size() {
  --size: 16px;
  @media (width > 1000px) {
    --size: 20px;
  }
  result: var(--size);
}

5. Defining Mixins

A mixin is in many ways similar to a custom function, but rather than extending/upgrading custom properties, mixins extend/upgrade nested style rules, making them reusable and customizable with arguments.

@mixin --gradient-text(
  --from <color>: mediumvioletred,
  --to <color>: teal,
  --angle: to bottom right,
) {
  @private {
    --gradient: linear-gradient(var(--angle), var(--from), var(--to));
  }
  color: var(--from, var(--to));

  @supports (background-clip: text) or (-webkit-background-clip: text) {
    background: var(--gradient, var(--from));
    color: transparent;
    -webkit-background-clip: text;
    background-clip: text;
  }
}

h1 {
  @apply --gradient-text(pink, powderblue);
}

h1 {
  --from: pink;
  --to: powderblue;
  --angle: to bottom right;
  color: var(--from, var(--to));
  --gradient: linear-gradient(var(--angle), var(--from), var(--to));

  @supports (background-clip: text) or (-webkit-background-clip: text) {
    background: var(--gradient, var(--from));
    color: transparent;
    -webkit-background-clip: text;
    background-clip: text;
  }
}

The entire @mixin feature is experimental and under active development, and is much less stable than @function. Expect things to change frequently for now.

5.1. The @mixin rule

The @mixin rule defines a mixin, and consists of a name, a list of mixin parameters, and a mixin body. (Identical to @function, save that it lacks a return type, and that the parameter list and enclosing parentheses are optional.)

<@mixin> = @mixin [<function-token> <function-parameter>#? ) | <ident-token> ]
{
  <block-contents>
}

The mixin body is parsed as if it were a nested declarations rule.

A @mixin rule cannot be a nested group rule; it is invalid within the body of a style rule.

5.1.1. The Mixin Prelude

The <function-token> or <ident-token> production must start with two dashes (U+002D HYPHEN-MINUS), similar to <dashed-ident>, or else the definition is invalid.

The name of the resulting mixin is given by the name of the <function-token> or <ident-token>. The optional mixin parameters are given by the <function-parameter> values (defaulting to an empty set).

If an <ident-token> is used, it is equivalent to a <function-token> followed by an empty parameter list.

The name of a @mixin rule is a tree-scoped name. If more than one @mixin exists for a given name, then the rule in the stronger cascade layer wins, and rules defined later win within the same layer.

If the mixin parameters contain the same <custom-property-name> more than once, then the @mixin rule is invalid.

If a mixin parameter has both a default value and a parameter type then the default value must parse successfully according to that parameter type’s syntax. Otherwise, the @mixin rule is invalid.

5.1.2. The Mixin Body

The body of a mixin is parsed as a nested declarations rule; it accepts properties, conditional group rules, and nested style rules, just like an ordinary style rule would. In particular, further mixins can be invoked.

In addition to everything normally valid in a style rule, the mixin body can contain one or more @contents rules, allowing a passed-in contents block to be substituted in.

5.2. Arguments and Local Variables

A mixin’s parameters define private properties in the mixin body, set to the value passed for the argument. As usual for private properties, these are accessible using var(), and shadow any same-named custom properties that might otherwise exist on the element. See § 5.5 Evaluating Mixins for details on this behavior.

@mixin --shadowed-values(--color2: green, --color3: green) {
  @private { --color3: blue; }
  background: linear-gradient(var(--color1), var(--color2), var(--color3));
}
p {
  --color1: red;
  --color2: red;
  --color3: red;
  @apply --shadowed-values();
}

@mixin --only-descs(--arg) {
  color: var(--arg);
  & + * { color: var(--arg, red); }
}
.foo {
  @apply --only-descs(green);
}

5.3. The @contents Rule

In addition to accepting arguments passed by the <dashed-function> in the @apply rule, a mixin can accept a contents block. Any mixin can be passed a contents block, by giving the @apply rule invoking the mixin a block.

This allows the invoker of the mixin to pass an entire style block, which the mixin can then substitute into itself. This is useful, for example, if the mixin handles some common conditions for the author, and substitutes the contents block into a predefined @media or @container rule.

The syntax of a @contents at-rule is:

<@contents> = @contents [ { <declaration-list> } ]?

That is, it is either an empty statement ended immediately by a semicolon, or a fallback block treated as a nested declarations rule. The empty statement form behaves identically to passing an empty block.

• If the @apply rule invoking the mixin passed a contents block, the @contents is replaced with the contents block, treating it as a nested declarations rule.

• Otherwise (if the @apply rule did not pass a contents block), the @contents rule is replaced with its fallback block, treating it as a nested declarations rule.

Outside of a mixin body, the @contents rule is invalid and ignored.

Note: It’s valid for an @apply rule to pass a contents block, but the mixin not use it.

@mixin --one-column() {
  @media (width <= 800px) {
    @contents;
  }
}
@mixin --two-column() {
  @media (width > 800px) {
    @contents;
  }
}
body {
  @apply --one-column {
    display: flex;
    flex-flow: column;
  }
  @apply --two-column {
    display: grid;
    grid-template-columns: 60px 60px;
  }
}

5.4. The @apply Rule

The @apply rule applies a mixin, causing it to substitute into the rule in place of the @apply rule itself.

Its grammar is:

<@apply> = @apply [ <dashed-ident> | <dashed-function> ] [ { <declaration-list> } ]?;

.foo {
  @apply --one;
  /* Invokes the --one mixin, with no arguments or contents. */

  @apply --two(blue);
  /* Invokes --two with one argument, and no contents. */

  @apply --three {color: red;}
  /* Invokes --three with no arguments, but with contents. */

  @apply --four(blue) {color: red;}
  /* Invokes --four with both an argument and contents. */
}

The @apply rule is only valid in the body of a style rule or nested group rule; using it in any other context causes it to be invalid and ignored.

@apply rules are processed before any styles are applied, as they effectively modify the stylesheet itself. (Similar, in effect, to how conditional group rules adjust which properties and rules are active in a stylesheet before styles are applied.)

The @apply rule applies the mixin named by the <dashed-ident> or the <dashed-function>’s name. If no such mixin exists, the @apply does nothing.

If passed a <dashed-function>, the arguments passed to the <dashed-function> are mapped to the mixin’s arguments; if more arguments are passed than the length of the mixin’s argument list, the @apply application does nothing. (Passing too few arguments is fine; the missing arguments take their default values instead.) A <dashed-ident> passes no arguments. (That is, @apply --foo; is identical to @apply --foo();.)

If the @apply rule has a <declaration-list> block, that block is passed as the mixin’s contents block.

.foo {
  @apply --no-args;
}
.bar {
  @apply --no-args();
}

@mixin --just-contents() {
  @contents { color: red; }
  /* `color: red` is the fallback content */
}

.foo {
  @apply --just-contents;
  /* fallback, substitutes with `color: red;` */
}
.bar {
  @apply --just-contents {};
  /* substitutes with nothing at all */
}

5.5. Evaluating Mixins

TODO rewrite to use the new @private concepts.

At a high level, mixins are applied by substituting their contents at the location they’re @apply'd.

Unfortunately, the exact mechanics of mixin substitution are somewhat more complicated, to ensure that local references, variables, and other concepts work in a "natural" way.

When a mixin is applied, the @apply rule referencing it is replaced with the mixin result, with each property value in the mixin result having its value replaced by an anonymous custom function with the following properties:

• The function parameters are identical to the mixin parameters. (The function’s invocation has some adjustments; see below.)

• The function body is identical to the mixin body, minus any @result rules, plus a result descriptor containing the original value of the property this anonymous function is replacing.

Additionally, the arguments passed to the mixin are evaluated and stored on the @apply'd element, to ensure they obtain the "expected" value from that element, rather than unexpectedly evaluating in a descendant element’s context:

• For every mixin parameter, a custom property is added to the top level of the mixin result, with a hygienic name and a value of the corresponding @apply() argument. This custom property is unobservable to the page; it only exists for UA purposes.

  Also, a custom property registration with that name, a syntax of the parameter type, an inherit flag of "true", and no initial value, is added to the tree of that element.

• Each anonymous function invocation has its arguments set to var() functions referring to the corresponding custom property name created in the previous bullet point.

@mixin --same-size(--size <length>) {
  @result {
    &, & > * {
      width: calc(10 * var(--size));
    }
  }
}
.parent {
  font-size: 10px;
  @apply --same-size(1em);
}
.parent > .child {
  font-size: 20px;
}

@property --magic-arg1 {
  syntax: "<length>";
  inherits: true;
  /* initial-value: don't worry about it; */
}
@function --anonfunc1(--arg1) {
  result: calc(10 * var(--arg1));
}
@function --anonfunc2(--arg1) {
  result: calc(10 * var(--arg1));
}
.parent {
  font-size: 10px;
  --magic-arg1: 1em; /* resolves based on font-size here */
  width: --anonfunc1(var(--magic-arg1));
}
.parent > .child {
  font-size: 20px;
  width: --anonfunc2(var(--magic-arg1));
  /* --magic-arg1 is 10px, since it was resolved on the parent */
}

Note: In practice, this anonymous custom function can usually be completely hypothetical, and a direct substitution used instead. It’s required only to make variables and other element-relative values resolve correctly.

div {
  @apply --colorized-squish(tomato);
}

/* "wraps" an element in colored arrows */
@mixin --squish(--left-color <color>,
                --right-color <color>: var(--left-color)) {
  @result {
    &::before {
      content: "🡆";
      background-color: var(--left-color);
    }
    &::after {
      content: "🡄";
      background-color: var(--right-color);
    }
  }
}

/* colors the element, and auto-generates a border color
   and the "squish" colors from it */
@mixin --colorized-squish(--color <color>) {
  @result {
    background-color: var(--color);
    border: 2px solid oklch(from var(--color) calc(l - 0.1) c h);
    @apply --squish(oklch(from var(--color) calc(l - 0.3) c h),
                    oklch(from var(--color) calc(l - 0.2) c h));
  }
}

div {
  @apply --colorized-squish(tomato);
}

@mixin --colorized-squish(--color <color>) {
  /* Lift the `@apply squish();` arguments out into local vars */
  --s-arg1: oklch(from var(--color) calc(l - 0.3) c h);
  --s-arg2: oklch(from var(--color) calc(l - 0.2) c h);
  @result {
    background-color: var(--color);
    border: 2px solid oklch(from var(--color) calc(l - 0.1) c h);
    /* Replace the `@apply --squish();` with its @result,
       transformed to wrap the property values in
       anonymous functions. */
    &::before {
      content: --s1(var(--s-arg1), var(--s-arg2));
      background-color: --s2(var(--s-arg1), var(--s-arg2));
    }
    &::after {
      content: --s3(var(--s-arg1), var(--s-arg2));
      background-color: --s4(var(--s-arg1), var(--s-arg2));
    }
  }
}
@function --s1(--left-color <color>,
               --right-color <color>: var(--left-color)) {
  result: "🡆";
}
@function --s2(--left-color <color>,
               --right-color <color>: var(--left-color)) {
  result: var(--left-color);
}
@function --s3(--left-color <color>,
               --right-color <color>: var(--left-color)) {
  result: "🡄";
}
@function --s4(--left-color <color>,
               --right-color <color>: var(--left-color)) {
  result: var(--right-color);
}

div {
  /* Lift the `@apply --colorized-squish();` argument out into a var */
  --cs-arg1: tomato;
  /* Replace the `@apply --colorized-squish();` with (part of)
     its @result, again with values wrapped in anonymous functions. */
  background-color: --cs1(var(--cs-arg1));
  border: --cs2(var(--cs-arg1));
  &::before {
    /* Note that --cs-arg1 is inherited here from div */
    content: --cs3(var(--cs-arg1));
    background-color: --cs4(var(--cs-arg1));
  }
  &::after {
    content: --cs5(var(--cs-arg1));
    background-color: --cs6(var(--cs-arg1));
  }
}
@function --cs1(--color <color>) {
  result: var(--color);
}
@function --cs2(--color <color>) {
  result: 2px solid oklch(from var(--color) calc(l - 0.1) c h);
}

/* These four generated functions all look identical, they
   just call into the correct generated function from
   --squish()'s unfolding. */
@function --cs3(--color <color>) {
  /* The --colorized-squish() local vars (created by the
    first desugaring) are turned into function local vars. */
  --s-arg1: oklch(from var(--color) calc(l - 0.3) c h);
  --s-arg2: oklch(from var(--color) calc(l - 0.2) c h);
  result: --s1(var(--s-arg1), var(--s-arg2));
}
@function --cs4(--color <color>) {
  --s-arg1: oklch(from var(--color) calc(l - 0.3) c h);
  --s-arg2: oklch(from var(--color) calc(l - 0.2) c h);
  result: --s2(var(--s-arg1), var(--s-arg2));
}
@function --cs5(--color <color>) {
  --s-arg1: oklch(from var(--color) calc(l - 0.3) c h);
  --s-arg2: oklch(from var(--color) calc(l - 0.2) c h);
  result: --s3(var(--s-arg1), var(--s-arg2));
}
@function --cs6(--color <color>) {
  --s-arg1: oklch(from var(--color) calc(l - 0.3) c h);
  --s-arg2: oklch(from var(--color) calc(l - 0.2) c h);
  result: --s4(var(--s-arg1), var(--s-arg2));
}

/* These are copied from the previous desugaring */
@function --s1(--left-color <color>,
               --right-color <color>: var(--left-color)) {
  result: "🡆";
}
@function --s2(--left-color <color>,
               --right-color <color>: var(--left-color)) {
  result: var(--left-color);
}
@function --s3(--left-color <color>,
               --right-color <color>: var(--left-color)) {
  result: "🡄";
}
@function --s4(--left-color <color>,
               --right-color <color>: var(--left-color)) {
  result: var(--right-color);
}

/* Initial Code, same as main example */
div {
  @apply --colorized-squish(tomato);
}

/* "wraps" an element in colored arrows */
@mixin --squish(--left-color <color>,
                --right-color <color>: var(--left-color)) {
  @result {
    &::before {
      content: "🡆";
      background-color: var(--left-color);
    }
    &::after {
      content: "🡄";
      background-color: var(--right-color);
    }
  }
}

/* colors the element, and auto-generates a border color
   and the "squish" colors from it */
@mixin --colorized-squish(--color <color>) {
  @result {
    background-color: var(--color);
    border: 2px solid oklch(from var(--color) calc(l - 0.1) c h);
    @apply --squish(oklch(from var(--color) calc(l - 0.3) c h),
                    oklch(from var(--color) calc(l - 0.2) c h));
  }
}


/* First desugar, unfolding --colorized-squish()*/

div {
  /* Pull out the --colorized-squish() argument */
  --cs-arg1: tomato;
  /* Swap the @apply with the --colorized-squish() @result,
     with values wrapped in anonymous functions. */
  background-color: --cs1(var(--cs-arg1));
  border: --cs2(var(--cs-arg1));
  /* The equivalent transform here is wrapping the
     @apply args in anonymous functions. */
  @apply --squish(--cs3(--cs-arg1),
                --cs4(--cs-arg1));
}
@function --cs1(--color <color>) {
  result: var(--color);
}
@function --cs2(--color <color>) {
  result: 2px solid oklch(from var(--color) calc(l - 0.1) c h);
}
@function --cs3(--color <color>) {
  result: oklch(from var(--color) calc(l - 0.3) c h);
}
@function --cs4(--color <color>) {
  result: oklch(from var(--color) calc(l - 0.2) c h);
}
@mixin --squish(--left-color <color>,
                --right-color <color>: var(--left-color)) {
  @result {
    &::before {
      content: "🡆";
      background-color: var(--left-color);
    }
    &::after {
      content: "🡄";
      background-color: var(--right-color);
    }
  }
}


/* Second desugar, unfolding --squish() */
div {
  --cs-arg1: tomato;
  background-color: --cs1(var(--cs-arg1));
  border: --cs1(var(--cs-arg1));
  /* Pull out the --squish() args now. */
  --s-arg1: --cs3(--cs-arg1);
  --s-arg2: --cs4(--cs-arg1);
  /* And swap the @apply with the --squish() @result,
     with values wrapped in anonymous functions. */
  &::before {
    content: --s1(var(--s-arg1), var(--s-arg2));
    background-color: --s2(var(--s-arg1), var(--s-arg2));
  }
  &::after {
    content: --s3(var(--s-arg1), var(--s-arg2));
    background-color: --s4(var(--s-arg1), var(--s-arg2));
  }
}
@function --cs1(--color <color>) {
  result: var(--color);
}
@function --cs2(--color <color>) {
  result: 2px solid oklch(from var(--color) calc(l - 0.1) c h);
}
@function --cs3(--color <color>) {
  result: oklch(from var(--color) calc(l - 0.3) c h);
}
@function --cs4(--color <color>) {
  result: oklch(from var(--color) calc(l - 0.2) c h);
}
@function --s1(--left-color <color>,
               --right-color <color>: var(--left-color)) {
  result: "🡆";
}
@function --s2(--left-color <color>,
               --right-color <color>: var(--left-color)) {
  result: var(--left-color);
}
@function --s3(--left-color <color>,
               --right-color <color>: var(--left-color)) {
  result: "🡄";
}
@function --s4(--left-color <color>,
               --right-color <color>: var(--left-color)) {
  result: var(--right-color);
}

6. Private Custom Properties: the @private rule

"Temporary variables" are a common tool in programming languages, letting one give a name to an intermediate result, then use that name in another value to make it easier to read. One can use custom properties for this purpose, but they’re automatically exposed to descendant elements on the page, and might clash with existing custom properties used on the element, requiring some degree of coordination between otherwise-independent usages. Mixins make this problem even worse, since its mixin parameters are exposed as custom properties for the applying element and its descendants to use.

To address these use-cases, the @private rule can be nested inside of any style rule, and defines private properties: a special kind of custom property which is only usable inside the same style rule (and any nested style rules).

<@private> = @private { <declaration-rule-list> }

The @private rule is only valid nested as a child of a style rule or a nested group rule. In any other context, it is invalid.

A @private rule can only contain custom properties and nested group rules (in which case it passes this same restriction to their contents). Any other contents are invalid and will be ignored, but do not invalidate the @private rule itself.

When a style rule contains any @private rules (including those nested in nested group rules), the set of custom properties they contain define the style rule’s private property names, a set of custom property names. Within the style rule (and any nested rules), any custom property with that name is actually a private property, and any reference to a custom property of that name (for example, with a var()) is a reference to the private property.

A private property is a special variant of a custom property:

• It is considered to be a different property from any non-private custom property, even if they share the same name.

• Two private properties with the same name are considered the same property if and only if they have the same nearest style rule ancestor that has their name in its private property names.

• It is not exposed to the page via any CSSOM APIs. (For example, CSSStyleDeclaration.getPropertyValue() can’t get its value, the CSSStyleDeclaration enumeration won’t contain them, etc.) It is only accessible to styles in the same style rule that defined them, or its nested rules.

Distinct private properties with the same name are, for all intents and purposes, separate properties. They can exist together on a single element at the same time, carry their own distinct values, etc.

Note: Because private properties are different from same-named custom properties, custom property registrations do not normally apply to them. (They apply to the non-private custom property, instead.) In some cases, such as mixin parameters, CSS can still give them a custom property registration.

Applying a mixin with @apply effectively substitutes the mixin in-place, so a mixin sees any private properties visible to the style rule it’s substituted into (if it doesn’t override them with its own mixin parameters or private properties).

What about custom functions? If they refer to a custom property not defined in the function, should they see an outer private property? I’m inclined to say yes; extracting some styles to a custom function should, generally, act identically to inlining them.

section {
  --size: 2px;
  &, & > *, & > * > * {
    border-width: var(--size);
  }
}
section > h1 {
  --size: 4px;
}
section > h1 > small {
  --size: 3px;
}

section {
  @private { --size: 2px; }
  &, & > *, & > * > * {
    border-width: var(--size);
  }
}
section > h1 {
  --size: 4px;
}
section > h1 > small {
  --size: 3px;
}

section {
  --f7bd60b7: 2px;
  border-width: var(--f7bd60b7);
}
section > h1 {
  --size: 4px;
  border-width: var(--f7bd60b7);
}
section > h1 > small {
  --size: 3px;
  border-width: var(--f7bd60b7);
}

Note: While private properties ensure that elements and their descendants can’t accidentally have their variables overwritten by accidental collisions, they’re still evaluated as normal for properties, which can interact with other properties set in other style rules.

section {
  font-size: 10px;
  @private { --size: .2em; }
  &, & > *, & > * > * {
    border-width: var(--size);
  }
}
section > h1 {
  font-size: 20px;
}
section > h1 > small {
  font-size: 15px;
}

section {
  font-size: 10px;
  border-width: .2em;
}
section > h1 {
  font-size: 20px;
  border-width: .2em;
}
section > h1 > small {
  font-size: 15px;
  border-width: .2em;
}

@function --as-length(--x <length>) { result: var(--x); }
section {
  font-size: 10px;
  @private { --size: --as-length(.2em); }
  &, & > *, & > * > * {
    border-width: var(--size);
  }
}
section > h1 {
  font-size: 20px;
}
section > h1 > small {
  font-size: 15px;
}

@mixin --untyped(--size) {
  &, & > *, & > * > * {
    border-width: var(--size);
  }
}
@mixin --typed(--size <length>) {
  &, & > *, & > * > * {
    border-width: var(--size);
  }
}

section {
  @apply --untyped(2px);
}
section > h1 {
  --size: 4px;
}
section > h1 > small {
  --size: 3px;
}

section {
  font-size: 10px;
  @apply --untyped(.2em);
}
section > h1 {
  font-size: 20px;
}
section > h1 > small {
  font-size: 15px;
}

section {
  font-size: 10px;
  @apply --typed(.2em);
}
section > h1 {
  font-size: 20px;
}
section > h1 > small {
  font-size: 15px;
}

7. CSSOM

TODO Supply the OM for @mixin/etc.

7.1. The CSSFunctionRule Interface

The CSSFunctionRule interface represents a @function rule.

[Exposed=Window]
interface CSSFunctionRule : CSSGroupingRule {
  readonly attribute CSSOMString name;
  sequence<FunctionParameter> getParameters();
  readonly attribute CSSOMString returnType;
};

name, of type CSSOMString, readonly

The name of the custom function.

returnType, of type CSSOMString, readonly

The return type of the custom function, represented as a syntax string. If the custom function has no return type, returns "*".

dictionary FunctionParameter {
  required CSSOMString name;
  required CSSOMString type;
  CSSOMString defaultValue;
};

name

The name of the function parameter.

type

The type of the function parameter, represented as a syntax string, or "*" if the parameter has no type.

defaultValue

The default value of the function parameter, or `null` if the argument does not have a default.

While declarations may be specified directly within a @function rule, they are not represented as such in the CSSOM. Instead, consecutive segments of declarations appear as if wrapped in CSSFunctionDeclarations rules.

Note: This also applies to the "leading" declarations in the @function rule, i.e those that do not follow another nested rule.

@function --bar() {
  --x: 42;
  result: var(--y);
  @media (width > 1000px) {
    /* ... */
  }
  --y: var(--x);
}

@function --bar() {
  /* CSSFunctionDeclarations { */
    --x: 42;
    result: var(--y);
  /* } */
  @media (width > 1000px) {
    /* ... */
  }
  /* CSSFunctionDeclarations { */
    --y: var(--x);
  /* } */
}

7.2. The CSSFunctionDeclarations Interface

The CSSFunctionDeclarations interface represents a run of consecutive declarations within a @function rule.

[Exposed=Window]
interface CSSFunctionDescriptors : CSSStyleDeclaration {
  attribute [LegacyNullToEmptyString] CSSOMString result;
};

[Exposed=Window]
interface CSSFunctionDeclarations : CSSRule {
  [SameObject, PutForwards=cssText] readonly attribute CSSFunctionDescriptors style;
};

The CSSFunctionDeclarations rule, like CSSNestedDeclarations, serializes as if its declaration block had been serialized directly.

7.3. The CSSMixinRule Interface

The CSSMixinRule interface represents a @mixin rule.

[Exposed=Window]
interface CSSMixinRule : CSSGroupingRule {
  readonly attribute CSSOMString name;
  sequence<FunctionParameter> getParameters();
  readonly attribute boolean contents;
};

name, of type CSSOMString, readonly

The result of serialize an identifier on the mixin’s name.

getParameters()

Returns function parameters associated with the mixin, excluding any '@contents' parameter.

contents, of type boolean, readonly

True if the mixin accepts a contents block, and false otherwise.

While declarations may be specified directly within a @mixin rule, they are not represented as such in the CSSOM. Instead, consecutive segments of declarations appear as if wrapped in CSSNestedDeclarations rules.

7.4. The CSSApplyBlockRule Interface

The CSSApplyBlockRule interface represents an @apply rule with a contents block.

[Exposed=Window]
interface CSSApplyBlockRule : CSSGroupingRule {
  readonly attribute CSSOMString name;
  sequence<CSSOMString> getArguments();
};

name, of type CSSOMString, readonly

If the @apply rule has an associated <dashed-ident>, the result of serialize an identifier on that ident. Otherwise, the result of serialize an identifier on the name of the associated <dashed-function>.

getArguments()

Returns a sequence of arguments as strings, each item serialized as if it had been the specified value of a custom property.

The child CSS rules of a CSSApplyBlockRule represent the contents block of the @apply rule.

As for CSSMixinRule, consecutive segments of declarations specified directly within the contents block of an @apply rule are represented as CSSNestedDeclarations.

7.5. The CSSApplyStatementRule Interface

The CSSApplyStatementRule interface represents an @apply rule without a contents block.

[Exposed=Window]
interface CSSApplyStatementRule : CSSRule { 
  readonly attribute CSSOMString name;
  sequence<CSSOMString> getArguments();
};

name, of type CSSOMString, readonly

The same as CSSApplyBlockRule.name.

getArguments()

The same as CSSApplyBlockRule.getArguments().

7.6. The CSSContentsBlockRule Interface

The CSSContentsBlockRule interface represents a @contents rule with a fallback block.

[Exposed=Window]
interface CSSContentsBlockRule : CSSGroupingRule { };

The child CSS rules of a CSSContentsBlockRule represent the fallback block of the @contents rule.

As for CSSMixinRule and CSSApplyBlockRule, consecutive segments of declarations specified directly within the fallback block of a @contents rule are represented as CSSNestedDeclarations.

7.7. The CSSContentsStatementRule Interface

The CSSContentsStatementRule interface represents a @contents rule without a fallback block.

[Exposed=Window]
interface CSSContentsStatementRule : CSSRule { };

8. Privacy Considerations

The constructs defined by this specification are defined and used entirely within CSS; they expose no new information.

9. Security Considerations

No issues have been opened against this specification.

10. Changes

Changes since the First Public Working Draft of 15 May 2025:

• Made parentheses optional for mixins without parameters. (Issue 13015)

• Added Web Platform Tests coverage