[css-mixins-1] Using a scoping rule breaks author expectations, can we get rid of it?

[LeaVerou]

Background

From https://drafts.csswg.org/css-mixins/#result-rule

The mixin result is a scoped style rule, with the scoping root being the element the mixin’s styles are being applied to. (Unlike a traditional @scope rule, the scoping root here can be a pseudo-element, if the mixin is being applied to one.) There are no scoping limits.

One of the motivations for @macro was that because it does not return a scoping style rule, it's not bound by the same restrictions and can have more complex :has() conditions, sibling selectors etc.

IIRC the scoping style rule was introduced to make sure that local variables can be reliably used throughout the mixin. If the mechanics were that of naïve transclusion, this would not work:

@mixin --foo(--bar) {
	@result {
		border-color: var(--bar); /* works */
		& + p { 
			border-color: var(--bar) /* --bar is not defined here */
		}
	}
}

Why? Suppose --bar gets hygienically rewritten to --local-c5f2d35, the actual applied rule would look like this (value is the value passed via the mixin):

& {
	--local-c5f2d35: value;
	border-color: var(--local-c5f2d35);

	& + p { 
		border-color: var(--local-c5f2d35); 
	}
}

But --local-c5f2d35 would not inherit within & + p, so it would not be available.

Hence, the scoping.

However, I think having mixin rules be silently dropped because it's a scoping rule is incredibly confusing.

Consider this:

@mixin --foo(--arg <length>) {
	@result {
		width: var(--arg);
		
		& + p { margin-inline-start: 0 }
	}
}

Here, & + p would get dropped, even though it does not even use --arg!

Edit: I posted two polls on social media to test if my intuition reflects the majority expectation:

• https://x.com/LeaVerou/status/2037294835732734225
• https://front-end.social/@leaverou/116297811172593173
• https://bsky.app/profile/did:plc:eagnfcoqnbtzpkglrtej6ayg/post/3mhyr2rw2ls2r
• What mixin behavior feels most natural to you around nested rules? LeaVerou/blog#137

While we cannot reliably distinguish between A and B or C and D, since most authors missed the <length>, we can compare the two groups, and that gives a very strong signal that having rules be ignored is incredibly confusing and not natural to anyone. It is simply not an acceptable tradeoff IMO.

Brainstorming (edited)

But is the scoping rule the only way to address this problem? Conceptually, what authors are trying to do is pretty clear.

Take 1: Inject rewritten declaration in every nested rule

One solution would be to inject the rewritten properties in every rule within the mixin, i.e. rewrite to this:

& {
	--local-c5f2d35: value;
	border-color: var(--local-c5f2d35);

	& + p {
		--local-c5f2d35: value;
		border-color: var(--local-c5f2d35);
	}
}

Note that this would need to be done for nested rules as well. If the local declaration were only injected at the top level, this wouldn't work as expected:

@mixin --foo(--bar) {
	@result {
		border-color: var(--bar); /* works */
		& + p { 
			border-color: var(--bar) /* works! */
			& + p { 
				border-color: var(--bar) /* doesn't work! */
			}
		}
	}
}

The downside of this is that we lose inheritance: All values are now applied literally in every rule. However, these two facts help us:

1. We can't override local vars inside @result
2. We can't have regular rules outside of it (only conditional rules)

So the main issue is not around clobbering inherited values, but that the same literal value can have different meanings when used directly vs when inherited.

Take 2: Use inherit() to preferentially use the inherited value

One solution to this could be to preferentially use the inherited value, i.e. instead of injecting --local-c5f2d35: value;, inject --local-c5f2d35: inherit(--local-c5f2d35, value);. Since the custom property cannot possibly be present anywhere else (as it is hygienically rewritten to something that is guaranteed to avoid clashes with the outside world), this naturally sets it at the topmost level of each root and lets it inherit down naturally.

So the mixin above would inject this rule:

& {
	--local-c5f2d35: inherit(--local-c5f2d35, value);
	border-color: var(--local-c5f2d35); /* works */
		& + p { 
			--local-c5f2d35: inherit(--local-c5f2d35, value);
			border-color: var(--local-c5f2d35) /* works! */
			& + p { 
				--local-c5f2d35: inherit(--local-c5f2d35, value);
				border-color: var(--local-c5f2d35) /* works! */
			}
		}
}

Take 3: Double hygienic rewriting

But what is value? When is it resolved to a <length>? If it gets resolved at @apply we get very weird dependencies where ancestors get computed values from their children (thanks @andruud!)!

@mixin --sync-width(--arg <length>) {
	@result {
		width: var(--arg); /* 100px */
	
		#ancestor:has(&) {
			/* If 100px you have ancestors that depend on the computed values of their children?! */
			width: var(--arg); 
		}
	
		.child {
			width: var(--arg);
		}
	}
}

#ancestor {
	font-size: 20px;
}

#target {
	font-size: 10px;
	@apply --sync-width(10em);

	.child {
		font-size: 30px;
	}
}

One solution to that would be to resolve at the injected declarations, and otherwise pass 10em around as an untyped token stream. Conceptually, this would behave as if we had two hygienically rewritten properties: one untyped and one typed:

& {
	--arg-c5f2d35: inherit(--arg-c5f2d35, 10em); /* unregistered, so it stays 10em */
	--arg-c5f2d35-length: var(--arg-c5f2d35); 
	width: var(--arg-c5f2d35-length);

	#ancestor:has(&) {
		--arg-c5f2d35: inherit(--arg-c5f2d35, 10em); /* unregistered, so it stays 10em */
		--arg-c5f2d35-length: var(--arg-c5f2d35);
		width: var(--arg-c5f2d35-length);
	}

	.child {
		--arg-c5f2d35: inherit(--arg-c5f2d35, 10em); /* unregistered, so it stays 10em */
		--arg-c5f2d35-length: var(--arg-c5f2d35);
		width: var(--arg-c5f2d35-length);
	}
}

This would make #ancestor have a width of 200px and #target would still get 100px since the property inherits as a token stream, not a typed value. However, .child would get 300px. Is that desirable?

Take 4: Override in @scope

Take 3 above gives us typed properties that resolve differently on every element. Is that what we want though? It is inconsistent to how typed custom properties behave, as they inherit after being resolved.

We can't just use --arg-c5f2d35-length: inherit(--arg-c5f2d35-length, var(--arg-c5f2d35));: then #target would get #ancestor's inherited value, which is incredibly confusing.

It seems that, ideally, I think we'd want .child and #target to both get 100px, but #ancestor (and siblings, and generally anything outside #target's subtree) should resolve 10em using its own context, to avoid weird dependencies. Can we do that?

We can depend on the fact that that anything inside & is able to inherit both of these custom properties, the problem is that we cannot statically only inject the --arg-c5f2d35 declarations inside rules that are not in &'s subtree. But what if we injected an override that is guaranteed to take priority?

& {
	--arg-c5f2d35: inherit(--arg-c5f2d35, 10em); /* unregistered, so it stays 10em */
	--arg-c5f2d35-length: var(--arg-c5f2d35); 
	width: var(--arg-c5f2d35-length);

	#ancestor:has(&) {
		--arg-c5f2d35: inherit(--arg-c5f2d35, 10em); /* unregistered, so it stays 10em */
		--arg-c5f2d35-length: var(--arg-c5f2d35);
		width: var(--arg-c5f2d35-length);
	}

	.child {
		--arg-c5f2d35: inherit(--arg-c5f2d35, 10em); /* unregistered, so it stays 10em */
		--arg-c5f2d35-length: var(--arg-c5f2d35);
		width: var(--arg-c5f2d35-length);
	}

	@scope {
		& {
			/* Rules mirror the structure in the actual mixin, but @scope ensures rules outside &'s subtree are ignored */
			#ancestor:has(&),
			.child {
				--arg-c5f2d35-length: inherit;
			}
		}
	}
}

Since we're using the same selectors and we control the declarations on both ends, the override is guaranteed to apply, and @scope scopes it to just the target's subtree.

Note that we'd probably need to mirror the tree for applying the original declarations as well, otherwise layers etc could throw this off.

Take 5: inherit(--rewritten, value) everywhere except &

This seems like it would cover all cases, but what about this?

@mixin --foo(--arg <length> {
	@result {
		width: var(--arg);

		& + p {
			width: var(--arg);

			img {
				width: var(--arg);
			}
		}
	}
}

#target {
	font-size: 10px;
	@apply --foo(10em);
}

#target + p {
	font-size: 20px;
}

img {
	font-size: 30px;
}

Based on the algorithm above, the @scope would not cover #target img, so it would get 300px, not the expected 200px from its own ancestor!

We basically want the following:

• Typed properties always resolve on mixin target based on its own context no matter what
• Descendants of mixin target get inherited resolved values based on target's context
• All subtrees outside mixin target resolve the typed property using the root's element context, and then it inherits down.

So inherited --arg-c5f2d35-length always takes precedence except on &. We can do that with a slightly different override:

• Use --arg-c5f2d35-length: inherit(--arg-c5f2d35-length, value) everywhere
• Override with --arg-c5f2d35-length: value on &, in a way that is guaranteed to take precedence over any mixin declarations (e.g. theoretically a mixin could include nested rules for &&& {} that just target &, that should not override).

Anyhow, hopefully this may give folks ideas to take this further!

[tabatkins]

Doesn't work, unfortunately. The problem is that, when an argument passed to the mixin has element-specific behavior, we want to resolve it at the point of @apply on the applying element, and then have a consistent value for it no matter where it's used in the result.

That is:

@mixin --foo(--arg <length>) {
  @result {
    &, & > figure, & + p {
      width: var(--arg);
    }
  }
}
div {
  @apply --foo(10em);
  font-size: 10px;
}
div + p {
  font-size: 20px;
}
div > figure {
  font-size: 30px;
}

The div gets a 100px width regardless. Under your proposal, the figure would also get a 100px width, as it can inherit the value from its parent div and its font-size doesn't matter. But the p would get a 200px width, as it can't inherit so it falls back to resolving the 10em against itself. That's pretty confusing!

The current spec just prevents you from styling the p at all from within this mixin, so you don't run into the same problem. If you do want to style both elements, you have to lift the @apply up to their common parent, at which point we resolve the em length against that parent and all three styled elements again get the same width. Or you switch to a macro, which can't take arguments at all, and it's much more clear that you're resolving values locally:

@macro --foo {
  &, & > figure, & + p {
    width: 10em; /* this *obviously* relies on each element's font-size */
  }
}
div {
  @apply --foo;
  font-size: 10px;
  /* width: 10em; == 100px */
}
div + p {
  font-size: 20px;
  /* width: 10em; == 200px */
}
div > figure {
  font-size: 30px;
  /* width: 10em; == 300px */
}

[LeaVerou]

The div gets a 100px width regardless. Under your proposal, the figure would also get a 100px width, as it can inherit the value from its parent div and its font-size doesn't matter. But the p would get a 200px width, as it can't inherit so it falls back to resolving the 10em against itself. That's pretty confusing!

Fair. But that's only because of how we've defined arguments to work. What if & > figure could get --arg as a token stream, same as an unregistered property, and resolve it locally?

One way to do this could be to do the hygienic rewriting twice for arguments with a type, one with an unregistered custom property and one with a registered one, i.e if your --arg gets rewritten to --arg-c5f2d35 and --arg-c5f2d35-length, your mixin could produce this rule:

&, & > figure, & + p {
	--arg-c5f2d35: inherit(--arg-c5f2d35, 10em); /* unregistered, so it doesn't become 100px */
	--arg-c5f2d35-length: var(--arg-c5f2d35); /* 100px for div, 200px for > figure, 300px for & + p! */
	width: var(--arg-c5f2d35-length);
}

I'll need to think more about how this should behave with new local vars defined outside @result, but it seems like something with these broad strokes could perhaps work?

[andruud]

Under the current requirement of variable hygiene, and assuming that we're not going to drastically change very fundamental parts of CSS (like inheritance), I don't think this is hard, I think it's impossible. You easily end up in a situation where you need to know the value of var(--arg) right now based on information that can only exist in the future.

@mixin --sync-width(--arg <length>) {
   width: var(--arg); /* 100px */

   #ancestor:has(&) {
      width: var(--arg); /* 100px, as long as you have a time machine. */
   }
}

#ancestor {
  font-size: 20px;
}

#descendant {
  font-size: 10px;
  @apply --sync-width(10em);
}

Here, we need to evaluate var(--arg) in order to compute width on #ancestor, but doing that requires a computed value on an element below us.

   --arg-c5f2d35-length: var(--arg-c5f2d35); /* 100px for div, 200px for > figure, 300px for & + p! */

Isn't this the result we want to avoid?

But is the scoping rule the only way to address this problem?

If scoping is not acceptable, then it seems to me like we have to give up on hygienic arguments.

[tabatkins]

Yeah, the issue is that we want to resolve arguments immediately. Every programming language in the world (including CSS, with @function) resolves their arguments before evaluating their body. We can't quite do that, but we can fake it really close if the argument has a type, but only via the exact mechanism in the spec

@mixin --whatever(--arg <length>) { ... }
div {
  font-size: 10px;
  @apply --whatever(10em); /* if this doesn't make --arg 100px, it's broken, straight up */
}

Now to be clear, we are faking it. As Anders said, the mixin itself is resolved during stylesheet-building time, but the values need to wait until style-application time to know how to resolve. It's thus fundamentally impossible to "correctly" resolve the arguments before evaluating the body; like, logically impossible to do so. But, if they're typed, then storing them as (typed) custom properties on the applying element and using scoping + hygienic rewriting to let them safely inherit means we can fake it extremely well.

This is also why we can't automatically lift the arguments higher - not one level, not to the root. If we lift higher than the applying element, then the element-relative values resolve on the lifted element, not the applying element. That's dramatically worse than any of the other behaviors! Or, as I said in the call, we have to invent a dramatically new behavior that somehow avoids cycles while letting an ancestor resolve values based on a descendant's styles.

[tabatkins]

What if & > figure could get --arg as a token stream, same as an unregistered property, and resolve it locally?

Yes, this is exactly what we're trying to avoid in the general case. It is what you get if you have an untyped argument.

(In other words, because we lean on custom properties to actually do the technical lifting for us, you get the exact same behaviors, benefits, and drawbacks of using typed and untyped custom properties yourself. That's a known space for authors, and they can debug and fix problems the same way in Mixins that they do today when using custom props manually.)

[LeaVerou]

@andruud I think there may be a misunderstanding of what I'm proposing here because your example seems pretty straightforward to me.

The rule the mixin injects would become:

& {
	--arg-c5f2d35: inherit(--arg-c5f2d35, 10em);
	--arg-c5f2d35-length: var(--arg-c5f2d35);
	width: var(--arg-c5f2d35-length);

	#ancestor:has(&) {
		--arg-c5f2d35: inherit(--arg-c5f2d35, 10em);
		--arg-c5f2d35-length: var(--arg-c5f2d35);
		width: var(--arg-c5f2d35-length);
	}
}

Which would make the CSS:

#ancestor {
	font-size: 20px;
}

#descendant {
	font-size: 10px;

	& {
		--arg-c5f2d35: inherit(--arg-c5f2d35, 10em);
		--arg-c5f2d35-length: var(--arg-c5f2d35);
		width: var(--arg-c5f2d35-length);
	
		#ancestor:has(&) {
			--arg-c5f2d35: inherit(--arg-c5f2d35, 10em);
			--arg-c5f2d35-length: var(--arg-c5f2d35);
			width: var(--arg-c5f2d35-length);
		}
	}
}

Which would resolve to something equivalent to:

#ancestor {
	font-size: 20px;
}

#descendant {
	font-size: 10px;
	width: 100px;
}

#ancestor:has(#descendant) {
	width: 200px;
}

Note that even though --arg-c5f2d35 on #descendant would be inherited from #ancestor, it is the untyped property, so it would inherit 10em, not 200px.

--arg-c5f2d35-length: var(--arg-c5f2d35); /* 100px for div, 200px for > figure, 300px for & + p! */
Isn't this the result we want to avoid?

Is it? If we're not sure then we need developer research way before we think about implementation. Personally, I would find it extremely surprising if all of these resolved to 100px, or if #ancestor in your example got width: 10px even if it were possible to implement it that way.

I posted two polls on social media to test if my intuition reflects the majority expectation:

• https://x.com/LeaVerou/status/2037294835732734225
• https://front-end.social/@leaverou/116297811172593173
• https://bsky.app/profile/did:plc:eagnfcoqnbtzpkglrtej6ayg/post/3mhyr2rw2ls2r
• What mixin behavior feels most natural to you around nested rules? LeaVerou/blog#137

I can see that scoped mixins that resolve relative units using the same value throughout can be useful, but it does not seem like the majority use case or the dominant expectation to me.

[andruud]

@LeaVerou The original "function inversion model" in #12927 (unhygienic, unscoped) that we resolved on already does what you expect, I believe. We then chose (resolved) to add hygienic parameters on top of that. So I think you're more or less proposing that we drop hygiene.

--arg-c5f2d35-length: var(--arg-c5f2d35); /* 100px for div, 200px for > figure, 300px for & + p! */
Isn't this the result we want to avoid?

Is it?

@function --double-it(--arg) {
  --mywidth: 300px;
  result: calc(var(--arg) * 2);
}

div {
  --mywidth: 100px;
  width: --double-it(var(--mywidth));
}

How wide do you expect div to be here?

[LeaVerou]

@andruud I'm …lost about what in any of my comments may have sounded like I'm not proposing we drop hygienic rewriting. Being able to have local variables that cannot clash with outside variables is extremely important!

What I'm talking about is:

• When and on what element typed arguments should resolve
• My understanding (that @tabatkins confirmed) is that scoping was introduced to restrict rules to descendants, and rules had to be restricted to descendants only so that arguments could be used everywhere and still inherit as expected. I'm exploring whether there could be an alternative way to do those things without these restrictions which authors find extremely weird.

@function --double-it(--arg) {
--mywidth: 300px;
result: calc(var(--arg) * 2);
}

div {
--mywidth: 100px;
width: --double-it(var(--mywidth));
}
How wide do you expect div to be here?

This is what my expectation would be:

• --double-it would be called with an --arg of 100px
• --mywidth inside the function is rewritten to a different (unobservable) name and therefore has nothing to do with --mywidth on div, so it's effectively ignored as it's not used
• Therefore, result is 200px

[andruud]

• My understanding (that @tabatkins confirmed) is that scoping was introduced to restrict rules to descendants, and rules had to be restricted to descendants only so that arguments could be used everywhere and still inherit as expected.

Perhaps there was a misunderstanding? Arguments would be available everywhere anyway; inheritance is not needed for that. We introduced scoping only due to hygienic rewrites.

• --double-it would be called with an --arg of 100px

OK, good, just checking if there was a fundamental disagreement about resolving things at the call site.

---

Even if we subtract hygiene from the current spec, the following mixin still gives width:200px on <div>:

@mixin --double-it(--arg) {
  --mywidth: 300px;
  @result {
    width: calc(var(--arg) * 2);
  }
}

div {
  --mywidth: 100px;
  @apply --double-it(var(--mywidth));
}

That's because the final calc(var(--arg) * 2) value gets evaluated with a "synthetic" @function call stack above it which mirrors the @apply call stack. In other words, it evaluates as if you instead did:

@function --anonymous-generated-function(--arg) {
  --mywidth: 300px;
  result: calc(var(--arg) * 2);
}

div {
  --mywidth: 100px;
  width: --anonymous-generated-function(var(--mywidth));
}

(We do this to give locals/params a place to live so that var() can reach them via existing mechanisms. Although this interpretation of mixins into functions is a "rewrite", it must not be confused with "hygienic rewrite".)

If we look at another example:

@mixin --sync-size(--arg) {
  --mywidth: 200px;
  @result {
    width: var(--arg);
    & > .child {
      width: var(--arg);
    }
  }
}

.parent {
  --mywidth: 100px;
  @apply --sync-size(var(--mywidth));
}
.child {
  --mywidth: 300px;
}

You expected --double-it (function) to be called with --arg of 100px, which means that you expected --arg to hold an already-resolved value inside the function. Do you expect the same for the @apply --sync-size(var(--mywidth)) call?

If we again subtract hygiene from the current spec, we get a computed width of 100px on .parent and 300px on .child -- the value of var(--arg) (a parameter) shifted according to the element being targeted. This seems very bad.

If we maintain hygiene, we get a computed width of 100px on both .parent and .child, because var(--arg) resolves to the same thing everywhere in the mixin. In order to do this, we need to somehow resolve any var(--arg) (regardless of which element is targeted) in the context of the applying element. This is only realistically possible if the applying element is an ancestor of the element being targeted.

[LeaVerou]

Perhaps there was a misunderstanding? Arguments would be available everywhere anyway; inheritance is not needed for that. We introduced scoping only due to hygienic rewrites.

I wonder if we're using "scoping" differently? I'm not talking about hygiene at all. I'm talking about mixins having to return a scoped style rule. AFAIK that's not necessary for getting hygiene? You can conceptually just rewrite variables to unobservable names that are guaranteed not to clash.

As a result of mixins returning a style rule, certain rules in @result are silently dropped (basically anything outside the element the mixin is applied on and its descendants). I don't think this is an acceptable tradeoff. Look at the polls I posted: practically nobody expects this. People focused on the 100,100,100 vs 100,200,300 but the main thing I wanted to test was whether dropping the sibling selector was natural. It is not. At. All.

It also seems we need to get alignment first on what behavior would be ideal, if implementation constraints were not an issue, then see what are the best semantics we can reasonably implement. We're arguing tradeoffs before we have consensus on what behavior we're reducing from!

E.g. I think it should be a non-negotiable that siblings etc cannot be dropped. If we can get 100px,100px,100px somehow, with that constraint in place, even better. E.g. perhaps there is a way to not inject these declarations on element descendants, but only on the element itself and any elements outside its subtree, which would give you the current behavior for subtrees but wouldn't drop anything.

[andruud]

@LeaVerou Theoretically, would you be OK with renaming @macro to @mixin, and then figure out a new way of accessing scoped mixins in a way that makes it more clear to authors that it is in fact scoped? For example, "named scopes", or "parametric scopes":

.parent {
  --mywidth: 100px;
  /* Applies a named scope called `--sync-size`, defined elsewhere ... somehow. */
  @scope --sync-size(var(--mywidth));
}

[LeaVerou]

@andruud Yes, as long as we could have hygienically rewritten arguments, and I think something like the rewriting + injection mechanism I outlined above could be viable, with more work. I just edited the OP to address the issues with the original proposal and take it a bit further. It's not there yet, but it should be enough to give other folks ideas about how to evolve it further. But also, if arguments are too hard, there is value in shipping it without, as long as we can add them later.

Perhaps @scoped-mixin or @mixin-scoped? @scope instead of @apply is really interesting too. Is the idea that the same @mixin could be repurposed as either?

[andruud]

Is the idea that the same @mixin could be repurposed as either?

"Idea" is generous at this point. I think we would need a separate way to define a mixin "parametric scope fragment".