Improve mixin and extend docs in https://sass-lang.com/guide

[meatnordrink]

Hi,

I'd like to suggest that the example used in the Mixin example on the tutorial contains a complication that impedes quickly grasping the concept. Here's the example I mean:

@mixin transform($property) {
  -webkit-transform: $property;
  -ms-transform: $property;
  transform: $property;
}

Using a mixin with a name that's the same as one of the properties it contains is confusing, for someone who is new to the concept.

I understand that this example was chosen to demonstrate using a function where you can pass in a variable; but I think it would aid comprehension to lead with a more straightforward example, and follow with this, so the reader has less barrier to understanding basic function before moving on to understanding of full functionality.

Thank you.

[Awjin]

Thanks for bringing this up. I think that example is useful for demonstrating how mixins can clean up browser prefixes. However, I do agree that we could add a simpler explanation of mixins and possibly more context around its usage. I'm going to retarget this issue more broadly to address that.

Also, after the mixin section, there is a section that stresses the importance of extend. Modern best practices recommend mixins over extend, so that section should also be updated.

[stof]

Also, adding browser prefixes might not be the best example for using mixins. Most modern frameworks have stopped using mixins for that in favor of autoprefixer

[nex3]

Any suggested replacements would be appreciated 😃.

[jina]

How about:

@mixin theme($theme: DarkGray) {
  background: $theme;
  box-shadow: 0 0 1px rgba($theme, .25);
  color: #fff;
}

.info    { @include theme;                    }
.alert   { @include theme($theme: DarkRed);   }
.success { @include theme($theme: DarkGreen); }

(I used regular named CSS colors to avoid also introducing extra variables into the code but we can switch them to variabled colors if we prefer).