The Golden Rule
All code in any part of the code base should look like a single person typed it, no matter how many people contributed.
Code is written and maintained by people. Ensure your code is descriptive, well commented, and approachable by others.
Enforce standards mode in every browser possible with this simple doctype at the beginning of every HTML page.
- Use soft-tabs with two spaces
- Nested elements should be indented once (2 spaces)
- Don't include a trailing slash in self-closing elements
- Attributes should be lowercase.
- Always use double quotes ("), never single quotes.
- Boolean attributes should be used without quoted values to avoid redundancy.
HTML attributes should come in this particular order for easier reading of code.
- Section comments are separated from the previous block by two lines, and should have one following line of space.
- Prepend section headings with an equal sign (=), to make a Find operation easier.
- Use soft-tabs with two spaces
- When grouping selectors, keep individual selectors to a single line
- Include one space before the opening brace of declaration blocks
- Place closing braces of declaration blocks on a new line
- Include one space after
:in each property
- Each declaration should appear on its own line
- End all declarations with a semi-colon
- Comma-separated values should include a space after each comma
- Don't include spaces after commas in RGB or RGBa colors
- Do not specify units for zero values, e.g., margin: 0; instead of margin: 0px;
- Lowercase all hex values, e.g., #fff instead of #FFF
- Use shorthand hex values where available, e.g., #fff instead of #ffffff
- Quote attribute values in selectors, e.g., input[type="text"]
- Box (Display, Float, Position, Left, Top, Width, Height, Margin, Padding, etc.)
Use a new line for every block, list or table element, and indent every such child element to show heirarchy and improve understanding
Avoid Qualifying ID and class names with type selectors
For color values that permit, 3 character hexadecimal is preferred
Just don't do it.
Use greater specificity to workaround using !important; -- you will be judged in the afterlife.
Use the SMACSS Approach
Sass (or less or stylus, you choose)
- Mixins and variables go in scss/global/.
- Styles related to components/modules/views go in sass/components/.
- Sass and CSS from other projects goes in sass/vendor/.
All files get compiled into the main.scss stylesheet, and should be scoped accordingly.
The main.scss file serves as a "table of contents" and the @import directives should be listed with vendor dependencies first, then author dependencies and core stylesheets, then components.
Organize the components imports in a manner that makes sense, in other words, group components with the component they extend or inherit from.
@extends and @includes are likely to be overwritten by future elements, placing them at the top of the property list calls them out and avoids the beginning of a specificity war.
- @extends should be grouped together at the top of the selector.
- @includes should be grouped together after @extends.
- Regular styles for the current selector should be after @includes.
- Nested selectors appear last.
- Nested selectors using & should appear above child (>) nested selectors.
Limit nesting to 3 levels and/or 50 lines
Nesting selectors more than three levels deep and the code is at risk of being to reliant on HTML structure, overly-specific and difficult to understand.
50 lines is reasonable length for keeping an entire block on a code editor screen without having to scroll.
Variablize ALL THE THINGS!
- Variablize all colors.
- Numbers (other than 0 or 100%) with strong meaning or frequent use should be variables.
- Use hyphens (-) in variable names.
- Name variables based on what they represent, not their values, e.g. $text-size-large instead of $text-size-24.
- Colors, fonts, and base measurements are all great candidates for variables. If you find yourself writing a number other than 0 or 100% more than once, make it a variable.
- Most variables should be stored in the _variables.scss partial; however, it's acceptable to define component specific variables in the component files.
- In this case, the variables should be stored at the top of the file.
Try to stick with standard CSS comments, but you can use the Sass style (//) comments for trivial comments or quickly debugging.
Only One h1 Tag Per Page
While technically we could load a page up with h1 tags, it's a bad SEO practice and can cause penalties.
Use Title Attributes with Links
Using a title attribute in your anchor elements will improve accessibility when used the right way.
It is important to understand that the title attribute should be used to increase the meaning of the anchor tag.
How Much Will A Reader Read?
A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. William Strunk, Jr.
ARIA & Accessibility
Making it possible to provide an enhanced user experience for people with disabilities when using internet applications with assistive technologies.
banner - typically the "header" of the page
navigation - any navigation list, typically the nav element
main - the main content area
article - *the article role is not an ARIA landmark
complimentary - information that is tangentially related to the main content
contentinfo - contains information about the parent document such as copyrights and privacy statements
Using alt Text Properly
A few tips on how and when to use the alt attribute:
- Use the alt attribute for any image that is used as content.
- Use an empty alt atribute for any image that is decorative or not necessary for understanding the content of the page (alt=”“).
- Make sure the description of the image is useful. For example, if the image is your logo your alt should be your company name and not “logo”
The alt attribute is meant to help users using assitive techonology not miss any content, so make sure your text is helpful to anyone not seeing the image.
<.visually-hidden>- The Visually-Hidden class allows for 508 Compliance on an element needed for visually assisted users.