govCMS and GOV.AU UI-Kit

In the last half of 2016 the govCMS theme was in need of a refresh and Salsa Digital was approached to design and implement a fresh look to showcase govCMS. We began by looking at various government-centric starter kits for the theme build. As luck would have it, the DTA had just released a project called the DTO Design Guide & UI-Kit which seemed like the perfect candidate for the new govCMS theme. So let’s explore UI-Kit and how we used it.

What is the UI-Kit?

As taken from gov-au-ui-kit.apps.staging.digital.gov.au, UI-Kit is:

1. a draft design guide to build an accessible standardised look and feel for GOV.AU projects.

2. a lean and frugal CSS & JS framework that you can include in your project

What this means is you get both the theory (colours, fonts, sizing) and the practical examples (stylesheets, markup) for building a government-ready site.

The Design Guide gives you a colour palette, a set of text and form styles (headings, buttons, inputs, lists) as well as custom widget styles (accordions, sidebars, menus). Each of these is considered compliant with WCAG 2.0 AA accessibility standards, with screen-reader and vision-impaired considerations. As a developer, it’s worthwhile checking the provided markup examples as they make for a good screen reader accessibility reference.

The UI-Kit also includes Normalize (a stylesheet that removes some of the differences between standard browser styling), Bourbon (a toolset designed to simplify styling), Neat (a grid framework for constructing column layouts), and an implementation of the design guide (the stylesheets and markup) that you can use as a starting point on your site.

For those familiar with Bootstrap or Foundation; UI-Kit is used in a similar way. It’s included as your base layer, then site-specific styles are applied on top. Additionally, some styling can be called from UI-Kit’s tools when applicable. For example, when a link style is needed in a particular area, you can just call the UI-Kit’s ‘link-colours()’ mixin and your links are done. If you need three columns, you can call on Neat’s ‘outer-container()’ and ‘span-columns(4 of 12)’ mixin and you’ll have a three-column layout.

How does govCMS use it?

The new govCMS theme began its life as a culmination of many of the lessons learnt during development of government websites. We took the common elements and created a design that could be applied to a broad range of uses.

The UI-Kit Design Guide was then applied on top, taking in the base styles as the basis for the colour palette and typography. As well as these, the govCMS theme also uses implementations of UI-Kit’s links, form elements, breadcrumbs and a slightly modified sidebar with expand/collapse buttons. As soon as UI-Kit was included these elements were styled, meaning little work was needed to convert the design to code when it came to implementation.

For implementation, UI-Kit was placed in a vendor folder and its SASS stylesheets were imported before our custom styles. Having this separation allows UI-Kit’s future updates to be applied by replacing the folder contents.

Were there any challenges?

As with all styling projects; if you commit to using a styling framework there’s a level of restriction with what you can do, and UI-Kit is no different. We made the govCMS theme’s implementation easy for ourselves by committing to use the styles the UI-Kit provides. But, if we decide we want to break away from UI-Kit’s core design in the future, then we have some challenges.

Depending on how different your design requirements are, it could end up taking more time wrangling with overrides to justify any benefit from using UI-Kit. It’s a good idea to do an evaluation of your site’s needs during the design phase to determine if UI-Kit is the right starting point for you.

In a case more specific to Drupal, UI-Kit provides a selection of predefined classes that can be added to your style elements. This is good when you have complete freedom in how the HTML is added to the page (e.g. when building a static website) and it can save a lot of time. You write the elements as per the Design Guide and you have a fully working widget. But in the case of Drupal, it can be tricky to alter the HTML to match the exact requirements of the Design Guide’s widget. There is no easy way to map a widget’s styles without introducing additional Drupal templates or hook updates to inject class names, which can lead to maintenance and code-readability issues.

For example, our secondary sidebar menu was to be styled as per the local nav widget, however we opted to rewrite the style rather than use UI-Kit’s classes to avoid the hassle inherent when adding hook updates in Drupal templates.

Before, we mentioned UI-Kit lives in its own folder, but this separation breaks image URL paths for icons as the style is compiled from a different directory than UI-Kit is expecting. In these cases, style overrides were needed to point images to their correct path. For example, the external link icon used this custom styling to display correctly:

@function ui-kit-icon($filename) {

 @return url("../../vendor/gov-au-ui-kit/assets/img/icons/"+$filename);

}

a[rel~='external']::after {

 background-image: ui-kit-icon("external-link--aqua.svg") !important;

}

It would be good if UI-Kit allowed an asset root directory to be defined as a variable, so cases like this could be avoided.

We previously discussed ‘link-colours()’ being a mixin we can call to add link styles. If we wanted different looking links, it should be as simple as not calling this mixin and implementing our own custom mixin. But while UI-Kit gives the mixin to set link styles, it also explicitly uses this mixin on all link elements it assumes needs them. So if your site has an <article> tag in a <main> tag, those ‘link-colours()’ will be set to UI-Kit styles. While we can override these stylings in our custom sheets, it adds unnecessary complexity and maintenance burden to our styles. Having all styles as optional includes would stop these cases being an issue.

We have encountered this particular problem in subsequent themes, and our workaround was to make a copy of the offending file and place it in our custom theme, make the necessary changes, then include our new file in the stylesheet in place of the UI-Kit file. This allowed us to make ‘core’ modifications without polluting files in the UI-Kit. Should a time come when core UI-Kit files need to be updated to a newer version, we will have portions of the old version still lingering in our custom files, but the burden of tracking changes should be lessened by the changes being isolated.

Building from the challenges faced above, it would be a great idea to see better separation of styles within UI-Kit. To have the ability to include a mixin-only stylesheet for complete control over what you want to include, and where to include it in your styles, would mean no additional bloat from unused styles, fewer override concerns and more freedom in integration with existing systems. For those who prefer predefined classes, that could be an additional include.

Would we recommend UI-Kit?

UI-Kit is currently active on GitHub and it’s recommended to contribute to the project. The thing to remember is it’s still in an early draft release. As the project matures it could prove to be a very flexible and robust platform for theme building. As of right now, if you’re unencumbered with HTML flexibility and like the design, this is a great starting point. And even if you’re out for a vastly different look on your site, the UI-Kit’s Design Guide can still provide useful direction on implementation with regard to accessibility.