Formatting

Rules

General

• Use consistent indentation (Preference: Tabs)
• Opening brackets should exist on the same line as their last selector, preceded by a space
• Closing brackets should exist on their own line
• Block content should be indented
• Colons should be followed by a space, but never preceded by one
• Single quotes should be used, unless contents include one or more single quotes
• Use HEX format for colors, or RGBA for colors with alpha values
• If an RGBA value is an alpha variant of an existing color variable, use that variable in the RGBA function (e.g. rgba($clr__black, 0.5))
• HEX values should be uppercase and shorthand should be avoided
• Avoid specifying units for 0 values where allowed
• If a block consists of a single property, single-line presentation is acceptable- brackets should be separated from the property by spaces rather than line breaks (e.g. .txt__center { text-align: center; })
• Avoid using extra white space to align property values, except in the case of color variables where color highlighting in editors may benefit

Nesting

• Nesting syntax should be preferred for descendant selectors
• Nesting syntax with the use of & should be preferred for combination selectors
• Nesting syntax should be preceded by an empty line
• Avoid nesting more than 3 levels deep, or nesting unnecessarily

Properties

• Properties should not be separated by empty lines
• Properties should each exist on their own line
• Properties should end with a semicolon
• Property values separated by commas (beyond the first) should exist indented on their own lines
• Spaces should follow commas between function parameters
• Prefer unitless values for line-height

Selectors

• selectors should be in lowercase only
• Comma-separated selectors should each exist on their own line
• Selectors should be separated by an empty line
• Attribute values should be quoted (e.g. [type='checkbox'])
• Avoid targeting IDs
• Avoid sharing classes with JS, instead create separate classes prefixed with js__

Titling

• When sectioning a file without splitting it up (such as _variables.scss), use titles
• Titles should use // comment format
• Comment notations should be followed by a space
• Title should begin with 50 = to clearly stand out and act as a divider
• The final = should be followed by a space
• The line should end with the title name in all caps
• Titles should be followed by a blank line, and preceded by one if not first in the file

Example:

// ================================================== COLORS

Variables

• Prefer the use of existing global variables where appropriate
• Variablize commonly used values and values without self-evident meaning

Example

.selector {
	display: block;
	font-size: 1em;
	box-shadow: 0 0.5em 0.75em rgba($clr__black, 0.25),
	  0 0.1em 0.1em rgba($clr__black, 0.5);
	transform: scaleY(0);

	.descendant {
		display: block;
	}

	&._open {
		transform: scaleY(1);
	}
}

.second_selector,
.third_selector {
	background: $clr__primary;
}