Showing intent with mixin overrides

I write a lot of mixins in my SCSS. It makes managing large component based websites with strict consistency requirements possible.

Without them it's all too easy for a developer to overlook specific nuance that leads quickly maintenance issues. When a minor, but common pattern needs to be updated and isn’t available in one spot? "Hope you didn’t forget that one margin-top you used in 100 places that is now 5px smaller."

As with any abstraction writing mixin heavy SCSS comes with it’s own set of difficulties. Recently I've put some time into finding a clear and concise way to override specific mixin rules when a property doesn’t deserve to be parameterized.

Let’s say you have a standard subtitle mixin that you use through a site to define a set of typographical rules that should be common for various semantically similar elements.

@mixin subtitle {
  @include font(open-sans, semibold);
  @include font-sizes($header-font-sizes);
  margin:0 0 1em;
  color:$dark-grey;
}

What often happens deep into a project is that you find an edge case where, for a design reason, the standard subtitle margin of 1em doesn’t work. This change does not warrant it’s own parameter. The clutter and restriction a new parameter places on the mixin is not worth it. So you’d probably do this:

.special-situation {
  @include subtitle;
  margin-bottom:2em;
}

Great. It’s done. You can see that the special-situation is a a subtitle and it’s bottom margin is 2em. What this doesn’t tell you is if that margin is specific to this element or a change to the mixin. Throw in a few more mixin and try to find the intent the developer had.

.special-situation {
  @include subtitle;
  @include gutters;
  display:inline-block;
  max-width:50%;
  margin-bottom:2em;
  color:$blue;
}

It’s nearly impossible to tell why the margin has been set. You can’t know that one of the rules is an override and even if you guessed… which rule is it overriding?

Now. Don’t even consider breaking your declaration ordering style rules (you have those right?) by moving the rule below @include subtitle;. I’ve found something much better.

To solve this problem I'm using the @content control. This feature allows users of your mixing to attach a trailing block to any mixin inclusion that can be used to clearly relate overriding rules to the mixin. In the example above you’d have:

.special-situation {
  @include subtitle {
    margin-bottom:2em;
    color:$blue;
  }
  @include gutters;
  display:inline-block;
  max-width:50%;
}

It’s now completely transparent to any reader of this rule that the margin is 2em, and is overriding a rule within the subtitle!

Our design requirement is met, our mixin is clean of overly specific parameterization, and our rule ordering is correct! But more importantly than all of that, is the developers intent is clear and obvious during any maintenance on the styles in the future.