You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 8 Next »

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.

  • No labels