@robertakarobin/csslint

Robin's stylelint configurations, and a .css.ts-to-.css compiler.

CSS Styleguide

General principles:

Put everything (properties and classes) in alphabetical order.

Otherwise everyone comes up with their own order. Alphabetical isn't perfect, but at least it's consistent.

Nest all the things.

Deep nesting probably has little if any performance impact, it's DRYer, and also it's nice when the indentation of the CSS reflects the indentation of the content.

In the HTML class attribute, order classes

Order by:

1. Modifiers stick together, e.g. in the example below -high is related to button because its a modifier
2. Global before local
3. Alphabetically

Note that the order in the HTML class attribute doesn't actually matter. This is just an order that makes semantic sense.

<div class="button -high _submit -active"></div>

Class naming

We use kind-of a light version of BEM that trades a small risk of class collisions for brevity: we don't use the compound class names defined by BEM because they're annoyingly verbose, especially without a CSS pre-processor.

Less preferable (proper BEM):

<header class="_head">
	<h1 class="_head__title _head__title--icon">
		<i class="-head__title__icon"></i>
	</h1>
</header>

Preferable:

<header class="_head">
	<h1 class="_title -icon">
		<i class="_icon"></i>
	</h1>
</header>

Differences:

• If you're targeting an element that could only possibly be 1 specific HTML tag, target it with the tag name. Otherwise use a CSS class.

  ._hero {
  	& ._image {} /* Bad: The hero is probably only ever going to have a single <img> inside it, so `& img` is fine */
  	& img {} /* Good */
  }
  
  ._header {
  	& h1 {} /* Bad: A header could contain an h2, h3, h4... */
  	& ._title {} /* Good */
  }

• camelCase identifiers that are multiple words

  CSS ignores casing in CSS class names, so .fooBar is functionally the same as .foobar and .FOOBAR. But camelCasing is visually helpful for developers and the odds of it introducing a class name collision is remote.

  Do this:

  <li class="listItem_title"></li>

  Don't do this:

  <li class="list-item__title"></li>

• Prefix scoped/component/local classes with _

  These are classes which only make sense within the context of a particular component or block.

  .head {
  	& ._title {}
  	& ._subtitle {}
  }

  ...as opposed to global classes which can be used throughout an application:

  .button {}
  .modal {}

• Prefix variants/modifiers with -

  Classes which should only be used in conjunction with another class, describing a variant of it.

  .button {
  	& .-high {}
  	& .-low {}
  }
  .field {
  	& .-text {
  		& .-numeric {}
  	}
  }
  	```
  

Put properties for different states in different blocks, instead of overriding.

It's much clearer which properties belong to which state, and prevents the confusion that lots of overrides can cause. It comes at the cost of a little verbosity.

For example, consider a nav bar is vertical on larger viewports and horizontal on smaller viewports.

Don't do this:

.nav {
	background: #fff;
	display: flex;
	flex-direction: column;

	@media (smaller) {
		flex-direction: row;
	}
}

Do this:

.nav {
	background: #fff;

	@media (smaller) {
		display: flex;
		flex-direction: row;
	}

	@media (bigger) {
		display: flex;
		flex-direction: column;
	}
}

Note that since display: flex is declared by both states could be put in the base class, but the flex-direction properties don't really make sense without the context of display: flex, so semantically it's better as written.