General Standards
Formatting
Encoding
Make sure your editor uses UTF-8 as character encoding, without a byte order mark.
Specify the encoding in HTML templates and documents via <meta charset="utf-8">. Do not specify the encoding of style sheets as these assume UTF-8.
This will also mean you shouldn’t need to use entity references like & mdash;, & rdquo;, or & #x263a;, assuming the same encoding (UTF-8) is used for files and editors as well as among teams.
(More on encodings and when and how to specify them can be found in Handling character encodings in HTML and CSS.)
Indentation
Use soft-tabs with a four space indent (for readability and consistency across all of our codebases). Spaces are the only way to guarantee code renders the same in any person’s environment. Don’t use tabs or mix tabs and spaces for indentation.
Capitalization
All code should be lowercase: This applies to HTML element names, attributes, attribute values, CSS selectors, properties, and property values (with the exception of strings).
Trailing Whitespace
Remove trailing white spaces since they are unnecessary and can complicate diffs. To make this easy, configure your editor to "show invisibles". This will allow you to eliminate end of line whitespace, eliminate unintended blank line whitespace, and avoid polluting commits.
Line Breaks
Use a new line for every block, list, or table element, and indent every such child element. Indent each nested html rule as well, to reflect hierarchy and improve readability.
Code Validity
Use valid code unless that is not possible due to otherwise unattainable performance goals regarding file size, CSS validator bugs, or requiring proprietary syntax.
Use tools such as the W3C HTML validator and W3C CSS validator to test.
File organization
Variables
We use a number of variables in our styles and in order to make sure they all load in before any files that are dependent on them, all variable should live in the _variables.scss file.
Mixins
We also have a number of scss mixins in our styles and they all reside within the mixins folder in the lib/styles directory. This includes all vendor mixins (such as bourbon, neat, and breakpoint), and any custom mixins we create. Customs mixins should be split into multiple files based off their purpose to improve readability & maintainability.
Z-Index
Our Z-Index scale is defined in _variables.scss, and it provides a total of nine indices spread across three categories: low, medium, and high. Each of these categories has a specific purpose:
- low: Provides mid-range z-index values used for the body of any current interface. The majority of the site is set to the z-body-mid value.
- medium: Provides high z-index values used to create the effect of being above a given interface. These are primarily used for popups, toasts, floating headers, and similar components.
- high: Provides low z-index values used to create the effect of being beneath a given interface. These are primarily used for background components.
Stacking order is a uniquely odd thing. If you are running into issues, please read "What No One Told You About Z-Index", as it's a great overview of how stacking order works. Pay particular attention to the Stacking Contexts. Ideally, we should create stacking contexts using position and z-index as opposed to using the opacity hack.
Typography
All typographical base definitions should reside in the global _typography.scss file.
Media Queries
We use breakpoint to define media queries. Specific breakpoints should be defined in the _variables.scss file. This allows us to fine-tune media queries across the site all at once. If a component needs a specific media query breakpoint, define it at the top of the file in which the component-specific breakpoint is used.
Our standard breakpoints are:
- Phone: 320px wide
- Tablet: 768px wide
- Laptop: 990px wide
- Desktop: 1200px wide
Browser Support
Due to limitations in our Angular codebase, we are currently only supporting the follwowing modern browsers:
- Chrome
- Firefox
- Safari
- IE9+