Philosophy

Before getting into the lower level coding recommendations we'll define what this project expects for all of its code. Composition is king.

• Containers do not assume content
• CSS for looks is separate from CSS for layout
• CSS should be semantic
• Avoid utility classes in markup

Containers and Content

By building containers that do not assume their contents it allows for greater flexibility. For instance, a column grid component usually pads in the inner content. Depending on the usage of the grid this "gutter" may not be desired. To overcome this developers usually have to add negative margin to their inner children to overcome the assumptions made by a container.

Another reason for containers to not assume content is around composition. It is much easier to build up quality user interactions when the components are easily mixed together. As soon as containers assume what is inside, the ability to easily compose components into larger components goes away.

Separate Layout and Looks

CSS is used for both layout and looks via styles. However, when building reusable and scalable CSS it is best to separate classes that are the core layout of a component and the classes that give looks to the component.

For example a button class should give the structure of a button. In order to enhance the button to look a certain way a class for looks should be added, for example button--primary.

These recommendations relate back to composition. By having a clean separation it is easy to compose different variations of a core component without having to rely on a lot of complex overrides.

Semantics

CSS must be semantic. This leads to easier to maintain code and code that can grow. A good example here relates to colors and alerts. It would be a bad idea to create a class color-red. A much better choice is color-alert--critical.

Semantics allow for the lower level color to change and keep the meaning in the code.

Utility Classes

Avoid creating and using utility classes. At first glance it may seem okay to add a "remove all margin" class or a "no left padding" class. However, these types of classes usually highlight a flaw in the existing components. The question to ask is "why do I need this one-off change?"

There will be cases that a utility class is needed, however, these classes should be mixed into a more semantic class. For example, if an article on a page needs to remove the left padding give that a better name for the specific type of article that needs to remove that padding. Maybe the article is picture heavy, give it class name of article--picture-heavy.

CSS Details

At low level it is good to have constraints in place. Constraint theory tells us that having some level of control in a system helps increase the throughput and maintainability of the system.

At a high level here is how to write the CSS.

• CSSGuidelines
• BEM
• Avoid styling HTML elements directly
• Limit selector specificity
• Use rem units
• Favor using extends over mixins to reduce CSS rules

Writing Code: BEM and CSSGuidelines

The code should follow the ideals described in the http://cssguidelin.es/. Some specifics to call out:

• Reverse footnote commenting
• Tilting
• Meaningful whitespace
• CSS selectors
• Single responsibility principle
• BEM naming

There are two rules that we do not follow. Do not add extra space for BEM elements and modifiers. Favor using extends in LESS over having a lot of CSS rules that get complied out.

rem Units

When building out components most measurements should favor using rem units. The exceptions to this rule are parts that should not scale. For example a border width should not grow or shrink based on screen resolution.

rem units are used because it provides a consistent and constant way to apply measurements to components. The largest reason to use rem units is to keep the proportions between typography and components inline. Measurements should be based in typography. Since typographical elements are the base of design they should be used to build out the rest of the application.

Components

Components are the smallest unit developed and consumed by this ui guide. Rules for developing components:

• Only apply margin and padding to components
• Margin and padding is built off of rem units
• Must support RTL and LTR
• Only have 4 sizes: large, default, small, and extra-small (all 4 not required)
• Must be documented for consumption

Code Location

For the most part file names are fairly self explanatory on what lives with them. For example, the file called buttons.less holds the code for the button components. For more reused parts here are some files and what can be found within them:

colors.less

The base colors for the site. See individual file for further explanation

measurements.less

Base values for widths and heights (e.g. margin, padding, borders).

mouse.less

Contains values for the mouse on screen.

typography.less

Contains basic site wide settings for text display

Adding Docs

To make adding documentation easier it is recommended to use this tool to create the escaped HTML. http://www.freeformatter.com/html-escape.html#ad-output Once you have that tool write your HTML as you would normally and then copy paste it into the tool. Use the output inside code blocks to show what you've done. A recommendation for making that easy is to use column selection in your editor. See the button documentation for examples.