Update

This was written in 2017. I now use Prettier to automatically enforce consistent styles.

Research and credits

After reading all the style guides referenced in this css-tricks article I have created my own style guide.

For all languages

• Use 2 spaces for indentation.
• Build mobile first.
• Commit when each section is complete.
• Write useful commit messages.
• Use lower case for nearly everything.

React.js

• I agree with airbnb on their choices. I use their rules with Eslint with only minor changes.
• Use tertiary with null instead of "&&" to reduce cognitive load.

HTML Preprocessors

• Paragraphs of text should always be placed in a p tag. Never use multiple br tags.
• Use multiple single-line comments.
• Always put quotes around attributes for readability.
• Use a master template.
• Use mixins.

SCSS

• Where possible only style classes instead of tags.
• Avoid absolute positioning. Only use when necessary.
• Only use !important in extremely rare situations.
• Put breakpoints in a style declaration (scss way instead of css way).
• Avoid any breakpoint apart from @include breakpoint(sm).
• Use rem font sizes.
• All text is in the HTML so it can be in the CMS.
• All colours are variables.
• Use CSS for circular and rectangular shapes.
• Use the smallest z-index needed. Reorder HTML markup instead of using z-index.
• Use // for comment blocks.
• Avoid specifying units for zero values.
• Avoid shorthand declarations unless you actually want to set everything.

File Organisation and Naming

• Never style global tags apart from in the structure.scss file.
• Import all files into a main.scss.
• All variables in one file.
• All z-index settings are in one file.
• Create a new SCSS file for each component.
• BEM styling for naming.
• Keep a flat structure for children and grandchildren.
• Every class contains the block name.
• Multiword block names are in camelScript.
• Use &__item and &--modifier.
• Use additional –modifier classes instead of overwriting variables.
• Use our mixins and helper classes.
• Typography is all contained in one file.
• Use global layout classes instead of repeating layout inside each component.

Spacing and ordering

• Always include ; in property declarations.
• Put spaces after : in property declarations.
• Put spaces before brackets in rule declarations.
• Put line breaks between rulesets.
• When grouping selectors, keep individual selectors to a single line.
• Place closing braces of declaration blocks on a new line.
• Each declaration should appear on its own line.
• Leave a blank line at the end of the document.
• Arrange property declarations in alphabetically order.

Example

.classnameExample {
	// mobile version of classnameExample
	@include span(12);
	height: 300px;

	// desktop version of classnameExample
	@include breakpoint(sm){
		@include span(6);

		&:last-of-type {
			@include last;
		}
	}

	// Modifiers
	&--light {
		background-color: $white;
		color: $black;
	}

	// Parent wrapper
	&__wrapper {
		background: $primary;
	}

	// Children and grandchildren in order of HTML
	&__inner {
		@include span(12);
		position: relative;
	}

	&__logo {
		position: absolute;
		bottom: 0;
		right: 0;
	}
}

JavaScript

• Use semi-colons.
• Put brackets around if statements.

Accessibility

Always use:

• Every button and link needs a focus and hover effect and additional text content so it can be understood out of context.
• Every input has a label.
• All images have alt tags.
• All text has a high contrast ratio at all times.
• All text on images have a filter.
• All text is larger than 12px.
• Skip to content hidden link.
• Aria states on all state changes.
• Set tabindex automatically.

Try to use:

• Use semantic tags [header, footer, main, nav].
• Use roles (search).
• Use aria-alerts.
• JavaScript fallbacks.