&yet's Code Guide

Standards for writing sane and maintainable front-end systems

Introduction

This guide has been written with the purpose of empowering members of &yet to write better front-end systems in Jade and Stylus. It follows standard CSS conventions but also introduces preferential choices of our team. Feel free to treat it as an inspiration for writing your own code guides.

Table of Contents

HTML

Syntax

  • Use two spaces for indentation (here's how to set it up in Sublime Text, Textmate or Emacs). Nested elements should be indented once.
  • Use single quotation marks for attributes.
  • Feel free to omit optional tags but mind the code's readability.
  • Add empty lines between major elements to improve readability (use your own judgement).
doctype html
html(lang='en')

  head
    meta(charset='utf-8')
    meta(name='viewport', content='width=device-width, initial-scale=1')

    link(rel='stylesheet', href='css/main.min.css')

Encoding

Use UTF-8 encoding and custom characters instead of HTML entities. To access the list of characters hit ⌘+⌃+Space (Command + Control + Space). This method of invoking special characters list might not work in certain apps like Sublime Text, but will work in Chrome or IM.

 head
    meta(charset='utf-8')
    title from &yet ❤︎

Attributes

  • Omit type attributes in CSS and Javascript.
  • Omit values in boolean attributes.
  • Comply to the following attribute order: class, id, data-*, src, href, type, title, alt and role.
link(rel='stylesheet', href='css/main.min.css')
input.form-input(type='text', required)
a.button(href='/', title='A buttton')

Tag Nesting

Complying with Jade syntax in some cases means extensive use of piping to separate plain text from nested tags (like em or strong).

To avoid unreadable and cumbersome markup use regular HTML tags.

For regular nesting scenarios use indentation or block expansion.

// Regular nesting
ul 
  li
    a(href='#') Link
  li: a(href='#') Link

// Correct
p A paragraph with <strong>emphasized text.</strong>

// Incorrect
p 
  | A paragraph with 
  strong emphasized text.

Class Chaining

Chain classes directly after the element.

a.list-item.active(href='')

Semantics and Accessibility

For structuring content make use of new HTML5 sectioning elements.

Add basic ARIA landmark roles that increase accessibility by assigning meaning to specific areas of the page. Here's a good rundown of roles by Steve Faulkner.

  header(role='banner')
    h1 This is a website
  main(role='main')
    p Main content of my site
  footer(role='contentinfo')
    p © 2015

Boilerplate

Feel free to use a bare-minimum and standard-compliant boilerplate as a starting point for templating—see on Github.

CSS

Syntax

  • Use two spaces for indentation, as in Jade.
  • Use colons after properties (despite Stylus allowing their omittance).
  • Use a space to separate the colon from the property value.
  • Fine tune your CSS vocabulary here.
  .selector
    property: value

Preprocessing

We are using Stylus as a preprocessor of choice. Go here for documentation.

Declaration Order

Put declarations in the following order:

  1. Display and box model
  2. Positioning
  3. Typography
  4. Color
  5. Other

See more examples on CSS Tricks.

  .selector
    display: block
    width: 100px
    height: 100px
    position: absolute
    top: 0
    left: 0
    font-family: sans-serif
    line-height: 1.5
    background: black
    cursor: pointer

Units and Colors

  • Omit units after “0”.
  • Omit leading “0”s in values (example: .5em not 0.5em).
  • Use unitless line heights.
  • Use pixels for element sizing.
  • Use pixels for font sizes.
  • To create different hues (shades) of one colour create a variable and use color operations such as darken() and lighten().
  • Defer to hex/RGBA for one-time colors (if their usage is necessary).
  • In case of hex use 3 character hexadecimal notation wherever possible (#fff not #ffffff).

Comments

  • Include sectioning comments at the beginning of the file and anywhere else inside it if necessary.
  • Prefix the section names with $ for better searchability.
  • For inline, local commenting use //
/*---------------------------------------------
* $BUTTONS
---------------------------------------------*/

// Comment

Specificity

Specificity determines which CSS rule is applied by the browsers to a given element.

Class Naming

More resources on class naming can be found here:

Media Queries

Put media queries at the end of the file, where the modified element was defined. Make sure styles affecting desktop resolutions are inside a media query as well, the only styles placed outside should be shared by all resolutions.

Modularisation

We are aiming towards building scalable and maintainable front-end systems, that are easy to pick up and contribute to even without prior knowledge of the codebase. That goal makes structure and architecture crucial. CSS should be divided into small, easily comprehensible modules that serve a single purpose (i.e. define reusable, standalone interface elements).

Use the following structure:

└── styl
    ├── globals
    │   ├── _variables.styl
    │   ├── _helpers.styl
    │   └── _colors.styl
    ├── libraries
    ├── templates
    │   ├── home.styl
    └── components
        ├── buttons.styl
        ├── type.styl
        ├── grid.styl
        └── forms.styl

Acknowledgements

This guide is a result of years of learning how to write good front-end. It wouldn't be possible without people who dedicated a great amount of time and poured their hearts into spreading the knowledge. Thank you.

Further materials