Recommended update to z-index guidelines

[zzzzBov]

I feel that the front-end guidelines in general are pretty good but z-index can be a pain point, and I don't feel that the current docs represent what I consider to be best practices.

The variables page in the "Frontend Guides" says the following about z-index:

• Name all used z-indexes with a variable.

• Have a z-index variable for each z-index used, and a separate variable, possibly aliased for where the z-index is used.

  $z_index-neg_1: -100;
  $z_index-neg_2: -200;
  $z_index-1: 100;
  
  $z_index-hide: $z_index-neg_2;
  $z_index-bg: $z_index-neg_1;
  $z_index-show: $z_index-1;
  

From my own experience I would make the following recommendations:

1. every z-index should have its own variable.
2. z-index values should be ordered numerically
3. z-index values should start at 1 and increment by 1 without skipping any numbers

• magic numbers like 9999 and 100 shouldn't be necessary in the majority of cases.
• in some edge cases it is acceptable to repeat the same z-index value.

4. special cases where z-index ranges are used outside of CSS (typically JavaScript) should be noted with a comment

//good example
$dropdown-index: 1;
$tooltip-index: 2;
//indexes 3-5 used for widget animation
$modal-index: 6;
$menu-index: 7;

//alternative good example
$menu-index: 7;
$modal-index: 6;
//indexes 3-5 used for widget animation
$tooltip-index: 2;
$dropdown-index: 1;


//bad example
$dropdown-index: 100;
$modal-index: 9999;
$tooltip-index: 50;

---

The reason why I recommend every z-index having its own variable (#1) is to make it easier to change values in the future when bugs are found or new features are added. You won't have to go digging through source code to find any other z-indexes because they'll all be in the same place.

z-index values should be ordered numerically (#2) which I think is relatively obvious in that it allows a developer to easily tell the stacking order for components on the page. High-low or low-high doesn't really matter, as much as making it obvious which items are on top and which items are on the bottom.

z-index values should not skip numbers (#3) because there's no need for larger numbers, and large numbers make it harder to tell if other z-index values are "hiding" elsewhere in code. If you see values 1, 2, 3, and 4 and you need to place an item at position 3, it makes sense to bump 3 and 4 to 4 and 5 respectively.

If, instead you see 1, 2, 100, 9999 and you need to add an item between 2 and 100, which number do you pick? 3? 99? 50? what else is between 2 and 100? is there something else somewhere else using another z-index value that you have to go find? it's unclear. Avoid confusion. Counting is easy, and changing 1 2 3 4 to 1 2 3 4 5 is trivial even if it means occasionally you might have to change a handful of lines. The change is trivial to make and easy to double check in source control.

In some exceptional circumstances you may have two items that need the same z-index. In my experience it ends up being modals in modals that could be stacked in either order and the DOM is the decider for which is on top. Usually these cases are better served by a redesign (why do you need so many modals?) but at the end of the day, 1 2 3 3 4 isn't all that bad (so long as you leave a comment explaining the duplicate).

Special cases occasionally happen (#4) and it's important that the stacking order is maintained somewhere so changes can be reasoned about. When animating z-index values or using dynamic z-index values it's useful to leave a comment explaining the range that's off-limits and where it's used.