COmanage Style Guide

This style guide is a living document for COmanage 4.0 and higher.

Background

As larger numbers of developers participate in the COmanage project, the project must provide a set of guidelines to help developers

• create consistent interface elements within core code and plugins;
• understand the reasoning behind UI/UX choices; and 
• theme the application to meet the needs of a specific deployment.

Additionally, as COmanage gets included in a suite of Internet 2 tools that may benefit from coherency in theme or element design, the project can likewise provide guidance for how this may be accomplished while adopting common approaches where possible.

This Style Guide includes layout guidance, element screenshots, and occasional code samples with explanations for how to implement them. When appropriate, the guide explains the reasoning behind specific elements.

Contents

Constraints and Assumptions

The COmanage UI/UX is itself guided by a number of important considerations that impact the choices of user interface elements, the tooling used to build them, the theme, layout, and fonts, and even client/server interactions which impact the user experience.

1. Synchronous request / response cycle

   Provisioning (using Registry data to create or remove access to applications and services) is a fundamental feature of COmanage Registry. For now, the project requires that all actions that result in provisioning be synchronous so that users receive feedback on them in real time.
   
   

2. Keep tooling to a minimum

   COmanage’s adopters have significantly different development resources. In an effort to lower the boundaries to plugin development or theme customization, the project keeps tooling requirements to a minimum. Driven by that aim, COmanage’s user interface code is intentionally simple, structured within the CakePHP framework, and requires only a text editor to modify. Developers must understand the basics of PHP and, specifically, CakePHP. Beyond this, we aim to adopt few and widely understood libraries, and we weigh the selection of these both by their ability to serve the project’s needs as well as by the library’s stability and size of its user base. Development that requires separate tooling or a separate build step (e.g. Node/NPM, CSS pre-processing, etc) is avoided.
   
   

3. COmanage is a project in motion

   Like all software, COmanage must grow to meet the feature needs of its adopters while keeping up with dependencies that change over time. COmanage Registry 4.0 uses the Bootstrap framework (currently at version 4). An interface library such as Bootstrap provides useful features such as mobile breakpoints, common interface elements, and common design patterns. Bootstrap was selected because of its wide adoption, simplicity, and existing dependency on jQuery - which is already heavily leveraged by COmanage. However, COmanage also attempts to strike a balance between reliance on such libraries and the use of COmanage-specific markup laid out using CSS. Structures for forms, tables, and common layouts are documented in this Style Guide.  (Note that COmanage Registry versions 2 and 3 were built on the now end-of-life MDL library; guidance is provided (link coming) for how to convert Plugins that were built in earlier versions.)
    
   As the number of features in COmanage Registry continues to grow, the navigation and layout paradigms must address and simplify added complexity. In other words, the Style Guide and interface elements presented within, though fixed for a time, will always remain a work in progress.
   
   

4. Accessibility

   COmanage’s user interface is built to conform to WCAG AA 2.0. Colors, UI features, and underlying markup are chosen and constrained with accessibility at the top of mind.

Custom Themes

COmanage Registry may be styled without touching the underlying code by creating a custom Theme. Registry Themes allow for custom header and footer markup as well as custom CSS which is loaded last among styles. This allows a Theme to override any aspect of the Registry styles directly within the COmanage application.

While the use of direct CSS within custom themes is powerful, it has the disadvantage of being brittle: if the underlying markup changes significantly between versions, the CSS of a theme will need to adapt. As a future enhancement, the project is considering the creation of a simple theme panel for colors and a logo that will protect less development-minded deployers from such changes.

Fonts

The font chosen for the COmange project is Noto Sans. The Noto fonts were designed specifically to cover all scripts found in the Unicode standard and was adopted by COmanage to simplify and enhance internationalization. Noto Sans comes in only two weights: Regular (400) and Bold (700).

Iconography

COmanage makes use of the Material Icons font library for most icons. Material Icons are licensed under the Apache license version 2.0. 

Font Awesome (free) is also present and used in a number of places, and jQuery UI Icons have been carried forward as part of legacy styling from versions prior to 1.0. The use of jQuery UI Icons will be deprecated in coming versions.

Colors

Interior background colors in COmanage should be few and tend toward grey-scale in an effort to make Custom Theming simpler. That is, deployers should be able to place a logo and color scheme in a custom theme without the need to significantly modify interior colors of the application. Guidance for changing the primary colors in a custom theme is below, and development will move forward with an eye on making this ever simpler. Link and text colors are set to comply with WCAG AA 2.0 contrast guidelines. 

Text colors

• The color for general hyperlinks is #06c. This color passes accessibility contrast checking on white and gray backgrounds down to #eee.
• The standard body font color is #222.
• Color for headings (h1, h2, h3, etc) is #555.

Form Field Colors

• Input focus color: #ffd (light yellow)
• Input error color: #fee (light pink)
• Input error outlines, and requirement markers (*): #f00 (red)

Primary colors

Background and border colors

Highlight colors

Changing primary colors in a custom theme

While this document can not cover the scope of all color changes you may wish to implement in a custom theme, the following CSS rules can be added to a custom theme and modified to change the primary default colors:

Loading Animation

Full-page loading animation

The loading animation in 3.3.0 is built from CSS and is intentionally simple. To fire the loading animation from a button or link, add “spin” to the css classes for that link and the ever present #co-loading div that contains the loading animation will be shown.

To launch or hide the loading animation programmatically, call displaySpinner(); or stopSpinner(); with javascript.

Mini loading animation

A smaller loading animation may be rendered with the following markup. Hiding it is up to the page that makes use of it.

<span class="co-loading-mini"><span></span><span></span><span></span></span>

An example of the mini loading animation can be seen when a dashboard widget is loaded.