Re: [csswg-drafts] [css-mixins-1] Auto-wrap mixin body in `@result` if omitted? (#13524)

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 `@function`s, 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:

```css
@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.

-- 
GitHub Notification of comment by tabatkins
Please view or discuss this issue at https://github.com/w3c/csswg-drafts/issues/13524#issuecomment-4014391551 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Friday, 6 March 2026 22:00:46 UTC