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.
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
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.
Most designs should be in self-contained components which do not rely upon the presence of other components, and work within any parent container
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.