UOWeb Design Framework Component Style Guide

The UOWeb 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 and Sass: Colors used throughout the site. And Sass documentation for mixins, etc.
  • 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.
  • Universal Components: Are Design Components that work on any site using the UOBanner module, even if the Cosmic theme is not used/installed.
  • 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)

While our styles are organized as above in the style guide, 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
  • universal-components: component-based styles available to uobanner users
  • 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, .listingtitle is a child element of .listingcontent, but we refer to it as .listingtitle instead of .listingcontent__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