Styleguide

A living styleguide is a reference that automatically stays up-to-date with the live website. This ensures that everyone working on the site always have a shared understanding of how the component parts that make up the site should look and behave.

Please familiarize yourself with the Styleguide's setup before doing work with it, including its underlying logic code style. If you have questions or run into issues while working with it, please don't hesitate to file an Issue on GitHub.

The styleguide is organized into the following sections:

Overview

This is the page you're currently reading.

Logic

This is documentation for the underlying Sass logic used to build many of the site's classes. It covers variables and maps, functions, and mixins.

TODO

Why this exists.

TODO

Why this exists.

Why Sass?

Internet Explorer is still a very popular desktop browser. The pre-processed logic Sass offers helps us ensure the site will look and perform well on this browser, as well as other less popular or less feature-rich devices.

Why not x technology?

Our technology choices are a compromise between ease of use for a wide audience, coordinating site content, browser support needs, and minimizing external dependencies. If you feel your favorite library, language, or tool could benefit the project, file an Issue on GitHub to talk about it.

We will not debate using:

Style authoring

Please follow these following guidelines when writing styles for this site:

stylelint

This site uses stylelint to help ensure consistent formatting. stylelint is a linter for Sass, much like how JSHint is a linter for JavaScript. Linters are sets of rules that help you watch out for potential formatting discrepancies and errors in your code.

Please make sure your preferred code editor supports stylelint, and to install support for it. This will help make Pull Requests easier for the site maintainers.

Comments

Use Sass-style comments (//). When writing comments that speak to the selector's overall purpose, keep them on their own line.

Please keep comments no more than 80 characters long. If you need more room, please use a line break to help keep things legible.

Exceptions

Mark any declaration that overrides the styleguide with an exception comment (// EXCEPTION:). This will help us identify and codify areas where the styleguide is weak and could be improved.

Hacks

Place a hack comment (// HACK:) after values when the declaration is atypical or isn't immediately self-evident (ex: browser compatibility hacks, z-index, etc. ).

Imports

Please use Sass to handle importing partials. Using CSS's @import rule is considered an anti-pattern, as it generates extra HTTP requests. It's better to let Sass stitch files together.

Selectors

IDs

Do not use IDs as selectors. They create a high level of specificity that makes it difficult to work with.

!important

Only use !important to force immutability. A good example of this would be for styling the hidden attribute, where you want to guarantee that hidden content stays that way.

If you are using it to override something in the cascade, it signals an opportunity to re-write your CSS and lessen the specificity.

JavaScript hooks

Use either HTML data attributes or CSS classes with a prefix of js- as a hook for JavaScript. For ease of maintenance, do not include visual styling with attributes or classes that are used for logic.

Custom Properties

Prefer using Sass variables over CSS custom properties, as they are not supported in IE 11.

Nesting

Avoid nesting selectors when possible. If you need to nest selectors, try to keep it only one level deep. Never nest your selectors more than two.

Exceptions to this are nesting pseudo classes and elements, media queries, and other features like @supports, where it makes sense to couple the selector with its parent.

State

Prefer using semantic selectors for state in place of CSS classes. For example, use [disabled] { … } in place of .is-disabled { … }.

Units

Prefer using relative units such as ems, rems, percentages, and viewport units over static units such as pixels (px).