UO Web Design Framework Component Style Guide

The UO Web Design Framework is a component based SASS framework used to create the Cosmic theme for University of Oregon websites. This front-end style guide documents the design components and the Sass variables, functions and mixins used to build sites with the Cosmic theme and the UOWeb Design Framework.

Organization

We categorize our CSS styles to make them easy to find and apply to our HTML.

Colors: Colors used throughout the site. The official UO Brand colors are available as part of the UO Web Design framework. They can be applied using the CSS custom properties defined as --uowdf-color-[colorname] where the colorname is the all-lowercase dash-seperated name of the color. For example, --uowdf-color-uo-green is the property used to define the "UO Green" color. The .palette-base-[colorname], and .palette-bg-[colorname] classes can be used to apply the color palette to numerous components. A list of all web palette colors can be found at the Official UO Brand Web Color Reference
Defaults: These are the default base styles applied to HTML elements.
Forms: Form components are specialized design components that are applied to forms or form elements.
Layouts: The layout styling for major parts of the page that are included with the theme.
Components: Design components are reusable designs that can be applied using just the CSS class names specified in the component.
Bindings: Bindings adapt the design framework to work within different environments (Drupal, Wordpress, etc)

Beyond these groups, our Sass files are organized in a file hierarchy like this:

init: Sass needed to load variables, 3rd-party libraries and custom mixins and functions.
base: default HTML styles
components: component-based styles
layout: component styles that only apply layout to major chunks of the page
bindings: "glue" styles which adapt the design framework to work within different environments (Drupal, Wordpress, etc)
style-guide: some helper files needed to build this automated style guide

Why BEM

We have chosen to use a lightly flexible version of the BEM naming scheme in our SASS/CSS for the following reasons.

Encapsulation: BEM style names makes it easy to make components which can easily be added or removed to the framework without having side effects on other elements.
Structural Independence: BEM Styles are not dependent on the exact HTML structure which allows them to be easily adapted to work inside multiple CMS' such as Drupal and Wordpress.
Edit Suite Integration: Edit Suite's concept of Styles and Modifiers easily adapts to the modifier concept of BEM.
Efficiency: BEM styles prevent deep nesting which can create CSS which consumes more output filesize and runs less efficiently.
Consistency: BEM styles provide a single consistent naming scheme across the web design framework.

Documentation on BEM can be found on the official website: http://getbem.com/introduction/ . Our usage of BEM relies upon the use of component level modifiers which affect subelements which is allowed but uncommon in BEM. We also occasionally use nested items when necessary, but limit to a single item deep of underscores (for example, .listing__title is a child element of .listing__content, but we refer to it as .listing__title instead of .listing__content__title).

Our SASS/CSS Design Guidelines

We try to retain the following guidelines when developing SASS within the UOWeb Design Framework.

Rarely if ever, use '#' (ID) selectors in CSS rules.

The '#' selector is dangerous because it only allows a single element to use that style, takes precedence over other styles, is challenging to deprecate (due to its higher specificity). The high specificity of the '#' selector can cause that design element to damage the integrity of nested subelements. The id specifier should still be used in HTML where appropriate, as it is effective for tying in via javascript.

Most designs should be in self-contained components which do not rely upon the presence of other components, and work within any parent container
!important should only be used on components that directly need to overwrite runtime javascript settings or integrate with a 3rd party component.
Components should only overwrite color/font settings if absolutely necessary to the design of the component

While tweaking relative font sizes within a component is very reasonable, tweaking the font family or the font color leads to potential issues as it makes the component prone to breaking in future design updates.

Important References