What is the purpose of the LESS lib-css mixin?

Question

The .lib-css() mixin is used heavily in Magento 2 LESS files. However its purpose is not apparent, and the mixin definitions don't provide any helpful documentation:

//
//  Add any css property
//  ---------------------------------------------

.lib-css(
    @_property,
    @_value,
    @_prefix: 0
) when (@_prefix = 1)
  and not (@_value = '')
  and not (@_value = false)
  and not (extract(@_value, 1) = false)
  and not (extract(@_value, 2) = false)
  and not (extract(@_value, 3) = false)
  and not (extract(@_value, 4) = false)
  and not (extract(@_value, 5) = false) {
  -webkit-@{_property}: @_value;
       -moz-@{_property}: @_value;
        -ms-@{_property}: @_value;
}

.lib-css(
    @_property,
    @_value,
    @_prefix: 0
) when not (@_value = '')
  and not (@_value = false)
  and not (extract(@_value, 1) = false)
  and not (extract(@_value, 2) = false)
  and not (extract(@_value, 3) = false)
  and not (extract(@_value, 4) = false)
  and not (extract(@_value, 5) = false) {
    @{_property}: @_value;
}

I could see why you would want to use the mixin to add vendor prefixes to bleeding edge CSS properties (although there are few properties where that is necessary any more), but the reason for outputting normal CSS properties using this mixin is not clear. Can anyone shed light on this?

Answer 1

The only uses I can see are the prefixes and removing previously declared rules:

Prefixes

body {
    .lib-css(transition, color .5s ease, @_prefix: 1);
}

Will output:

body {
    webkit-transition: color 0.5s ease;
    -moz-transition: color 0.5s ease;
    -ms-transition: color 0.5s ease;
    transition: color 0.5s ease;
}

Removing previously declared rules instead of unsetting them

.lib-css() gives the ability to remove every rule that uses a certain variable instead of unsetting them or setting them to 0 or none. For example lets say we want to remove every rule that uses @button__shadow. Such as:

.product-list button {
    .lib-css(box-shadow, @button__shadow);
}

If it was only for one element it would be easier to write box-shadow: none;. But if this is on say 20 elements, it will be quicker to remove them all like so:

@button__shadow: false;

This has the added benefit of using @variable: none as it reduces lines of code, instead of adding more.

So compare these two methods:

LESS

Method 1:

.product-list button {
    .lib-css(box-shadow, @button__shadow);
}

Method 2:

.product-list button {
    box-shadow: none;
}

Or alternatively

@button__shadow: 0;

Output

LESS

@button__shadow: false;

.product-list button {
    .lib-css(box-shadow, @button__shadow);
}

Output

There is no output, the rules aren't processed

This does seem like a good idea but the use cases seem pretty small. I'll more likely just use it for the prefixes. It would be much more useful if @variable: false could be set locally, for example only within one div, unfortunately I couldn't get this working.

Core usage

I've noticed some variables are set to false by default, such as ones in lib/web/css/source/lib/variables/_buttons.less, I presume this is so they aren't outputted until required. Also a good idea.

//  Default = secondary button
@button__color: @primary__color;
@button__background: @color-gray95;
@button__border: 1px solid @color-gray-darken2;
@button__gradient-color-start: false;
@button__gradient-color-end: false;

Answer 2

The .lib-css() mixin is used to set any css property if there is a value passed to it by a variable. (e.g.)

[![.class {
    .lib-css(border-radius, @button__border-radius);
    .lib-css(border, @button-primary__border);
    .lib-css(color, @button-primary__color);
    .lib-css(background, @color-gray94);
    .lib-css(padding, @indent__s);
}

Also .lib-css() can add -ms-, -webkit- and -moz- prefixes if needed.

If the variable is set to false, the .lib-css() mixin will add nothing to the code.

please review .lib-css variables

also you can find all less help under

<magento install directory>\lib\web\css\docs\utilities.html