Code Style Guide

HTML Guide

• Use all-lowercase for elements and attributes.
• Use line breaks to separate content into logical and relatively small chunks.
• Always use classes instead of IDs for styling. IDs should only be used for anchor link targets (or javascript targets).
• Use double quotes for attribute values, e.g. <p class="some-class">.
• Order attributes by importance, with required attributes always ordered first.
• Use all lowercase and kebab-case for class and ID names, e.g. <p class="some-named-class"> instead of <p class="somenamedclass">.
• Favor full words rather than abbreviations or truncations in class and ID names e.g. <p class="preview-description"> instead of <p class="prev-desc">.

Line Breaks

There should always be line breaks between elements. There should also be line breaks between the opening and closing tags of a parent element and any children it contains.

The only exception is in cases of inline content that occurs within text. In this case, the element should be written within the line of the text.

Indentation

Indent elements relative to their parents, so that each child is indented one tab deeper than its direct parent.

Indent to show that an element is nested inside of another element.

Tabs width should be set to 4-spaces.

Use tabs instead of spaces for indentation. Tabs should be set to four spaces wide.

Self-Closing Tags

Self-closing tags should be written without a slash at the end.

CSS Guide

• Include one declaration per line in a declaration block.
• Use lowercase and shorthand hex values, e.g., #aaa.
• Use single or double quotes consistently. Preference is for double quotes, e.g., content: "".
• Where allowed, avoid specifying units for zero-values, e.g., margin: 0 instead of margin: 0px.
• Include a semi-colon at the end of the last declaration in a declaration block.
• Separate each ruleset by a blank line.

Indentation

Use tabs instead of spaces for indentation. Tabs should be set to four spaces wide.

Properties should be indented one tab from the containing selector. Closing brackets should align to the selector.

Property Order

Alphabetize your CSS properties in each declaration block to make them easy to find.

Helpful hint: To quickly alphabetize properties in Sublime Text, highlight the lines you want to sort and go to Edit > Sort Lines or press F5.

Spacing

A single space between a selector and the opening curly bracket of the declaration block is preferred. There should also be a single space between the colon that follows a property name and the value that follows.

Class Names

Class names should be descriptive of role or meaning rather than of style. Avoid class names that do not carry obvious meaning.

Aim to write class names that are nouns rather than adjectives.

A good method for deciding if a class name is acceptable is to imagine someone reading your CSS who cannot look at the HTML. Would this person be able to make sense of the class? If not, try a more descriptive name.

Use all lowercase and kebab-case for class and ID names, e.g. <p class="some-named-class"> instead of <p class="somenamedclass">.

Favor full words rather than abbreviations or truncations in class and ID names e.g. <p class="preview-description"> instead of <p class="prev-desc">.

Comments & Organization

Make liberal use of comments to break CSS code into discrete sections. Sections should either cover types of global styles (e.g. "Typography") or specific components in your design system (e.g. "Product Listing Card"). It is also sometimes useful to breakup sections into sub-sections.