[css-mixins-1] Auto-wrap mixin body in `@result` if omitted?

[andruud]

As discussed in #13138 and also #12927, several people (perhaps most vocally @LeaVerou) felt that requiring an explicit @result rule was too "noisy":

@mixin --greenify() {
  @result {
    color: green;
    background: lime;
  }
}

Should we then make @result optional, by treating a mixin body absent of any @result rules as implicitly wrapped in @result?

The following would then be equivalent to the first example:

@mixin --greenify() {
    color: green;
    background: lime;
}

I would prefer if we did require @result, but I'd much rather do an implicit auto-wrap than consider @local again (see #13138 (comment)).

[LeaVerou]

I’m very strongly against requiring an explicit @result, or any other solution that unnecessarily complicates the base case. Once they ship, mixins will be used all over the place. They will be used almost as much as variables (essentially they are how you do variables that span multiple properties). Tiny mixins are not an edge case either, I suspect they would be used a fair bit to alias mixins so that multiple properties can be fed as input to components, in the same way as CSS variables are used today as input to components.

My main issue with an explicit @result is that it adds no additional signal about user intent, so it is just noise.
When there are locals, its purpose is clear (ish). When there aren’t, it serves no purpose. There is nothing to disambiguate. It’s just boilerplate. The complex case is getting in the way of the simple case, and while local vars are very useful, my prediction is that the simple case will be significantly more common.

I think, as a design principle, locals should not introduce any boilerplate to mixins that don't need locals. Not just for ergonomics, but also strategically: it means simple mixins can ship first and locals can be implemented later, without simple mixins having this weird wart that only makes sense once complex mixins ship.

To be clear, I'm not a huge fan of auto-wrapping. It introduces mode errors where you don’t know what you have until you’re done reading the mixin. But (like you) I think it's the lesser evil.

Thinking about it some more, I’m not a huge fan of @result in general. It breaks the natural mapping of mixin to CSS rule by introducing an additional level of nesting that does nothing. It also inverts priorities, making the mixin contents the special thing that needs to be set aside, and local computations the main thing. And has several other issues already mentioned in #13138, most importantly that it breaks down once nested rules are involved that require both output and computation: now you need to mirror the nested structure in two places and look in two places to understand what’s going on.

I think it’s worth exploring alternative syntaxes that preserve the design principle I listed above, while improving ergonomics for locals over @local and hopefully avoiding the design flaws of @result.

Looking at the previous syntax, it seems the motivation for @result was the verbosity of @local. What if we could reduce that verbosity? First, it is quite boilerplate-y that authors need to declare their intent to use a local multiple times. Why is that? Can they have a local variable and a regular variable with the same name, in the same scope? That seems rather confusing, which one does var(--foo) resolve to?
Assuming they cannot, @local also introduced an error condition: what happens when you have a local but you forget to use @local in one of the declarations?

What if they declared their local variables once with @local and then every instance of that variable in that scope was assumed to be the local? This would turn @andruud’s example from #13138 from this:

@mixin --m() {
  @local --a: /* stuff */;
  @local --d: /* stuff */;
  @local --c: /* stuff */;
  @local --d: /* stuff */;
  @media (magnificence > 3.1) {
    @local --d: /* stuff */;
  }
  @local --e: /* stuff */;
  @supports (accent-color:red) {
    @local --e: /* stuff */;
  }
  @local --f: /* collecting all the above stuff */;

  & {
    color: var(--f);
    accent-color: var(--f);
    &::before {
      content: "Hi";
    }
  }
}

to this:

@mixin --m() {
  @local --a: /* stuff */;
  @local --d: /* stuff */;
  @local --c: /* stuff */;
  --d: /* stuff */;
  @media (magnificence > 3.1) {
    --d: /* stuff */;
  }
  @local --e: /* stuff */;
  @supports (accent-color:red) {
    --e: /* stuff */;
  }
  @local --f: /* collecting all the above stuff */;

  & {
    color: var(--f);
    accent-color: var(--f);
    &::before {
      content: "Hi";
    }
  }
}

Which is still a little verbose, but O(N) on the number of variables, rather than O(Nk) on the number of variables × declarations that set them, so the verbosity is a little more contained. It also avoids the error condition I mentioned above.
Perhaps we could reduce verbosity even more by having a declaration-only @local that would support multiple variables:

@mixin --m() {
  @local --a, --d, --c, --e, --f;
  --a: /* stuff */;
  --d: /* stuff */;
  --c: /* stuff */;
  --d: /* stuff */;
  @media (magnificence > 3.1) {
    --d: /* stuff */;
  }
  --e: /* stuff */;
  @supports (accent-color:red) {
    --e: /* stuff */;
  }
  --f: /* collecting all the above stuff */;

  & {
    color: var(--f);
    accent-color: var(--f);
    &::before {
      content: "Hi";
    }
  }
}

I think something along these lines has several benefits:

• It is arguably more readable than the @result example because you know what you have upfront
• It does not introduce additional nesting levels like @result does and preserves natural mapping
• It works just fine for nested structures and keeps computation and output together
• It does not introduce mode errors like auto-wrapping.
• It mirrors function arguments nicely, which are also implicit locals without having to be declared as such all over the place
• It sidesteps all the open questions about where @result is and isn't allowed in that are listed at the end of [css-mixins-1] Should we be more explicit about the result? (@result) #13138

I’m also not sure about @local as a name, but bikeshedding can come later.

[tabatkins]

I think, as a design principle, locals should not introduce any boilerplate to mixins that don't need locals. Not just for ergonomics, but also strategically: it means simple mixins can ship first and locals can be implemented later, without simple mixins having this weird wart that only makes sense once complex mixins ship.

There is no shipping-complexity benefit to doing a "no locals" version of Mixins, fwiw. They're just another way to spell Mixin arguments, without the confusion of making them passable.

---

FWIW, I'm strongly for the @result rule, in the standard Mixin here. We already have existence proof that authors find the syntax parallel with @function/result to make sense. (Miriam's interview with Chris Coyier, where as Miriam showed off the basic syntax, Chris literally said something like "oh like the 'result' property, makes sense".)

I think we should really value that sort of mental-model consistency when we can, because Mixins and Functions have enormous functional and behavioral parallels and keeping their syntax and concepts as parallel as possible is a huge win I think. I do not believe the cost of @result in small Mixins is worth having a complete syntax break between the two and dealing with the complexity of how exactly locals are mixed with styles in conditionals/etc.

Remember, also, that we have a resolution to introduce a different rule that has the "unscoped"/"simple" behavior, where there's no locals, no hygiene, no scoping, and thus no need for an @result. I think a lot of those "small" Mixins would be perfectly fine just using that rule instead.

[LeaVerou]

Miriam's interview with Chris Coyier, where as Miriam showed off the basic syntax, Chris literally said something like "oh like the 'result' property, makes sense".

It would help to link to this interview (a time offset to this part would also be appreciated).
Going by the wording in your comment, "result property" sounds like @mirisuzanne was presenting functions, and I completely agree that result makes sense there!

Remember, also, that we have a resolution to introduce a different rule that has the "unscoped"/"simple" behavior, where there's no locals, no hygiene, no scoping, and thus no need for an @result. I think a lot of those "small" Mixins would be perfectly fine just using that rule instead.

Would these mixins support nested rules and other @apply rules, or is that the simpler form we discussed where they're basically shorthands and only support declarations?
If the former, I agree that would be fine (and possibly even the best of both worlds), but we should design them together, not leave this as a TODO. It's very hard to change authors' mental model once they internalize that they need to use a @result {} rule all over the place.

[tabatkins]

Yeah I would have linked the interview if I could find it again. I searched for a bit but failed. @mirisuzanne ?

---

Would these mixins support nested rules and other @apply rules, or is that the simpler form we discussed where they're basically shorthands and only support declarations?

I'm not sure what this "simpler form we discussed" is. The body of this alternate form is just a nested declarations block, exactly identical to what's allowed inside the @result of a normal mixin.

[mirisuzanne]

This is the live stream with Chris: https://www.oddbird.net/2026/01/22/winging-it-28/ (I don't have a time-stamp off hand)

[tabatkins]

@LeaVerou And now the @macro rule is defined, so you can see exactly what I was intending with it https://drafts.csswg.org/css-mixins-1/#macros

[LeaVerou]

@LeaVerou And now the @macro rule is defined, so you can see exactly what I was intending with it drafts.csswg.org/css-mixins-1#macros

The lack of parameters is a pretty serious limitation :/ E.g. many simple mixins may be mapping one argument scheme to another so they can't use this.

[tabatkins]

I explained my design choices over in the issue containing the resolution.

As far as I can tell, there's no way to give macros arguments. Like, at all. It's just impossible without a radically different execution model where the arguments are interpolated into the result in a purely tokenish fashion, incompatible with var(). (aka, like how Sass actually does its Mixins)

[LeaVerou]

@tabatkins

(Miriam's interview with Chris Coyier, where as Miriam showed off the basic syntax, Chris literally said something like "oh like the 'result' property, makes sense".)

Thanks for the video link @mirisuzanne. It's a little after 51:25. Though note that he also thought the first result property wins in functions (55:30), which may indicate a broader mental model disconnect.

Also I’ve observed that authors tend to express enthusiasm for features that solve their pain points (and mixins solve a HUGE pain point) and try to justify their design to themselves, regardless of what it is (unless it's egregiously bad, which is not the case here).

I explained my design choices over in the issue containing the resolution.

As far as I can tell, there's no way to give macros arguments. Like, at all. It's just impossible without a radically different execution model where the arguments are interpolated into the result in a purely tokenish fashion, incompatible with var(). (aka, like how Sass actually does its Mixins)

Fair. That makes sense for #12927, but it does mean that @macro does not completely address the issue discussed here.

Going back to your original comment…

FWIW, I'm strongly for the @result rule, in the standard Mixin here. We already have existence proof that authors find the syntax parallel with @function/result to make sense.

The question isn't whether the parallel makes sense, but whether its lack would not make sense. Functions and mixins have fundamentally different characteristics around their usage:

• In a function all declarations other than result are going to be local variables, so it would make no sense to require additional syntax for that. In a mixin, it's not clear that this will be the case. If you have data that most author mixins have local variables, it would be useful to share them!
• The "cost" of a @result rule is much higher than that of a result property. It's one extra level of nesting, and forces you to separate computation from result, which is not natural. It works in functions because the result is only one line, so nothing is separated. It gets even worse for nested rules, where the distance between computations and usage is even larger. We could address this with multiple @result rules that get merged, but that increases the noise even more.

Thinking about it some more, ultimately, we have a conflict between two models: One where declarations are local by default (functions, mixins with @result) and one where declarations are public by default (auto-wrapped mixins, other syntaxes like @local above, etc). I think the reason we are struggling to decide is a disconnect around what the relative proportions are of use cases where explicit locals / implicit result would produce better syntax vs use cases where implicit locals / explicit result would produce better syntax. I wonder if there's any way we could estimate this better. Or even if there's a reasonable design where authors declare what type of mixin they have, without complicating the mental model further. 🤔

I think we should really value that sort of mental-model consistency when we can, because Mixins and Functions have enormous functional and behavioral parallels and keeping their syntax and concepts as parallel as possible is a huge win I think.

Is the worry that if @result exists, then something like this will be confusing?

@mixin --button-container(--hue) {
	background: var(ident(--color- var(--hue) "-" 90));
	color: var(ident(--color- var(--hue) "-" 30));
	border-color: var(ident(--color- var(--hue) "-" 80));
}

@mixin --wa-button-style (--primary) {
	@apply --button-container(if(style(--primary): var(--hue-primary); var(--hue-neutral)));
}

whereas this will not be?

@mixin --container-button(--hue) {
	@result {
			background: var(ident(--color- var(--hue) "-" 90));
			color: var(ident(--color- var(--hue) "-" 30));
			border-color: var(ident(--color- var(--hue) "-" 80));
	}
}

@mixin --wa-button-style (--primary) {
	@result {
		@apply --button-container(if(style(--primary): var(--hue-primary): var(--hue-neutral)));
	}
}

Because to me, the former seems pretty self-explanatory, and much closer to how preprocessor mixins behave. It’s the latter that needs to be learned…

[tabatkins]

I think in your example, the Mixin syntax used is the least confusing aspect you need to understand. ^_^

But no, I don't think either of those are confusing. Neither of them use local variables, or custom properties at all. It's easy to understand in both cases.

What I think is potentially confusing is:

1. When you do use local variables, if they have a different syntax than local variables in @function, since so much of the syntax is otherwise identical between the two rules. This is especially the case if you happened to build up some boilerplate media/supports that you commonly use in your @functions, and then when you copy/paste it into your @mixin you either need to edit every single one to make them locals, or shrug and let them turn into custom props.
2. If you do use a different syntax like @local --foo: ...;, then intermixing locals and custom props, or potentially putting locals into nested rules. What's allowed and what's not doesn't seem immediately obvious.

That is, given something like this:

@mixin --foo() {
	@local --L1: ...;
	--P1: ...;
	@media (width < 800px) {
		@local --L2: ...;
		--P2: ...;
	}
	> .bar {
		@local --L3: ...;
		--P3: ...;
	}
	:hover {
		@local --L4: ...;
		--P4: ...;
	}
}

I don't think it's very clear, neither from a learning perspective in general nor from a scanning perspective when reading the code, that --L1 and --L2 are legal, but --L3 and --L4 are illegal, while all of the --Pn properties are legal. The @result separation makes this easy - you define locals outside, you define custom props inside, every single usage is legal.

There's a number of other small differences which I think are more likely to bite authors when they're intermixed like this and made to look and feel so similar. --P4's value resolves based on different information than --P1/2/3 (because it's on the child), while all the legal locals resolve identically. var(--P1) could resolve one way at the top level and in the :hover rule, but another way in the > .bar rule, since some other code could set it to a different value on the .bar child, while var(--L1) is guaranteed to resolve exactly the same in all locations. And of course, if you mess up and make something a custom prop when it could have been a local, you run the risk of colliding with another mixin that happens to do the same thing, or a custom prop used for other purposes on your page.

Just in general, locals and custom props act a decent bit differently in a lot of cases, and if an author tries to use one as the other, there's a lot of potential for confusion or bugs. I believe that a small syntax difference like the suggested @local isn't enough to give a good mental separation, and people will be encouraged by bog-standard "shorter is easier" instincts to leave the prefix off and just get custom props, leading to subtle bugs.

Having a strict location difference I think makes the mental separation easier. And since they're equal length but locals are probably indented less, if anything there'll probably be a slight default preference to create locals instead of custom props, which is good. (The bugs you can get from using a local when you meant a custom prop are likely just "your var reference somewhere else doesn't see any custom property defined", which is a lot easier to debug than accidental name collisions from using a custom prop when you meant a local.)

---

If you have data that most author mixins have local variables, it would be useful to share them!

To be clear, my design preference here is not dependent on whether it's more likely to have mixins with or without local variables. If practically nobody used locals, I could be swayed, but even if locals are a minority usage (which they probably will be), I think the learnability/understandability/transferability benefits of the body/result divide currently in the spec are worth the cost of a wrapping @result rule.

[LeaVerou]

I think in your example, the Mixin syntax used is the least confusing aspect you need to understand. ^_^

That’s intentional — I wanted a case where the bulk of the complexity is not in the mixin syntax.
Also, nobody made the claim that @result is confusing. The pushback is that it is repetitive boilerplate that reduces signal-to-noise ratio. If the vast majority of mixins used locals I could see the consistency argument, but I don't think that's the case.

I’m fine not using @local and auto-wrapping instead. I do think it should be possible to have multiple @result rules that are merged in that case so that authors don't have to separate computations from output.

Just in general, locals and custom props act a decent bit differently in a lot of cases, and if an author tries to use one as the other, there's a lot of potential for confusion or bugs. I believe that a small syntax difference like the suggested @local isn't enough to give a good mental separation, and people will be encouraged by bog-standard "shorter is easier" instincts to leave the prefix off and just get custom props, leading to subtle bugs.

If they're that different, I wonder if we need different syntax altogether, because even @result {} doesn't feel sufficient. 🤔
If anything, it makes that distinction less clear. Without documentation, nothing in the syntax indicates that variables outside of @result are local.

I don't think it's very clear, neither from a learning perspective in general nor from a scanning perspective when reading the code, that --L1 and --L2 are legal, but --L3 and --L4 are illegal, while all of the --Pn properties are legal. The @result separation makes this easy - you define locals outside, you define custom props inside, every single usage is legal.

Whoa. I had not realized locals cannot be defined within nested rules. Why?
In that case, I agree that @result {} is clearer, but frankly, that's extremely confusing in both syntaxes. I'm not sure there is a syntax where having things that look identical to custom properties but behave differently is not confusing… 🫤

This is yet another reason to (conceptually) auto-wrap: even if locals are not hard to implement (which makes sense, since you need them for parameters anyway), shipping a v1 without @result and without local definitions gives us more time to get locals right without this holding back the MVP. Even without locals, parameterized MVPs solve a ton of very pressing pain points.

[bradkemper]

Like @LeaVerou , I'm not a fan of nesting the results. I'm also not a fan of nesting locals or having @Local scattered all over. All those things make the code hard to read and make sense of.

What if local variables and parameters just started with three or four dashes instead of two? It would be a lot easier to read and understand, IMO. Then you wouldn't need a bunch of @ indicators all over.

[bradkemper]

If nesting something like this doesn't work as expected...

	> .bar {
		@local --L3: ...;
		--P3: ...;
	}

Then wouldn't the @results version have the same problem?

	> .bar {
		--L3: ...;
		@results {
			--P3: ...;
		}
	}

[LeaVerou]

What if local variables and parameters just started with three or four dashes instead of two? It would be a lot easier to read and understand, IMO. Then you wouldn't need a bunch of @ indicators all over.

These are already valid CSS variable names.