January 1, 2016

Notes on @mdo's HTML and CSS style guides

Happened to read a HTML and CSS style guides in http://codeguide.co when listening to Mark Otto - Bootstrap 4 and CSS architecture at scale | Full Stack Radio, as any style guides most of the commonly known ones are nothing new but still found these are pretty helpful, and is reflecting something I've learned from my current project.

I'll just paste those guides and demo code as a reference, credit to Mark Otto (@mdo), and full list is in http://codeguide.co.

Reducing markup

Whenever possible, avoid superfluous parent elements when writing HTML. Many times this requires iteration and refactoring, but produces less HTML. Take the following example:

<!-- Not so great -->
<span class="avatar">
  <img src="...">

<!-- Better -->
<img class="avatar" src="...">

Declaration order

Related property declarations should be grouped together following the order:

  1. Positioning
  2. Box model
  3. Typographic
  4. Visual

Positioning comes first because it can remove an element from the normal flow of the document and override box model related styles. The box model comes next as it dictates a component's dimensions and placement.

Everything else takes place inside the component or without impacting the previous two sections, and thus they come last.

.declaration-order {
  /* Positioning */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* Box-model */
  display: block;
  float: right;
  width: 100px;
  height: 100px;

  /* Typography */
  font: normal 13px "Helvetica Neue", sans-serif;
  line-height: 1.5;
  color: #333;
  text-align: center;

  /* Visual */
  background-color: #f5f5f5;
  border: 1px solid #e5e5e5;
  border-radius: 3px;

  /* Misc */
  opacity: 1;

I've always wanted some guides on this topic, putting positioning and box-model related stuff first does make sense.

Media query placement

Place media queries as close to their relevant rule sets whenever possible. Don't bundle them all in a separate stylesheet or at the end of the document. Doing so only makes it easier for folks to miss them in the future.

We used to have a separated single file called responsive.css to write all those media queries for various screen sizes, but later found that it was hard for anyone else to track these changes.

.element { ... }
.element-avatar { ... }
.element-selected { ... }

@media (min-width: 480px) {
  .element { ...}
  .element-avatar { ... }
  .element-selected { ... }

But different than the code above, I'd like to nest the media queries right inside the selector, instead of separating and grouping them in another place. This way you don't have to rewrite the selector another time and also can see them in one place so you won't miss it.

.element {
  @media (min-width: 480px) {
.element-avatar {
  @media (min-width: 480px) {

.element-selected {
  @media (min-width: 480px) {

Shorthand notation

Strive to limit use of shorthand declarations to instances where you must explicitly set all the available values. .. Excessive use of shorthand properties often leads to sloppier code with unnecessary overrides and unintended side effects.

/* Bad example */
.element {
  margin: 0 0 10px;
  background: red;
  background: url("image.jpg");
  border-radius: 3px 3px 0 0;

/* Good example */
.element {
  margin-bottom: 10px;
  background-color: red;
  background-image: url("image.jpg");
  border-top-left-radius: 3px;
  border-top-right-radius: 3px;

I'm still having problem for 3-value syntax like margin: 0 0 10px;, 2-value and 4-value syntax are fine, whenever I see it I still need a few extra seconds to convert it to top, left and right, bottom accordingly. I've seen some other guides recommending always using the shorthand notation but I guess might be good to have some exceptions. So personally really want to give this style a try: avoid excessive use of shorthand properties.

Share on Twitter Share the post
Qihuan Piao

Qihuan Piao

(aka kinopyo) is Chinese based in Tokyo. Software writer. He shares stories inspired him in this blog. His infamous line - "I feel calm when I kill those monsters, or people (in game)" shocks his friends deeply.

He also writes in Japanese and Chinese.