Argo Design System Pt. III: CSS Library

TLDR: Having achieved team alignment on each major design decision of Argo Product Language, we needed a way for developers to implement the system. Facing a shortage of available engineering resources, I volunteered to build out a CSS Library via which developers could instantiate our design components through classes, similar to Bootstrap. We also developed a governance system for designers to make change requests or addition suggestions via our Design System JIRA board. Additionally, I started a bi-weekly presentation and chat between the design and front-end teams called Frontend Guild in which we hashed out complex challenges regarding APL.

In need of a Development solution

With the design portion finished, developers needed a vector to implement APL into their code. In the previous installment of the Design System, this was achieved via a React based UI Toolkit, in which Sketch assets were converted to React components. Unfortunately, Digital faced two challenges.

First, the department wanted to move to a framework agnostic solution. While React provided many benefits, Engineering was wary of the risks of being too heavily dependent on a single framework. All the senior engineers had witnessed cycles of popular frameworks arising and becoming obsolete and they felt it wouldn’t be in the company’s best interest to rely on one.

Secondly, with aggressive rollout timelines for Argo Portal, Digital was extremely stretched for Engineering resources and was unable to spare any for the development of a UI toolkit.

Solution: CSS Library

As a result of both of these constraints, I successfully proposed to build a CSS Library. The pitch was that developers could apply our design system components and styles with relative ease and speed through a series of CSS classes similarly to Bootstrap. Having over eight years of experience writing CSS and being central to management of the new Design System, I was uniquely suited for this project.

Finding a Documentation Solution

The CSS Library would be useless without a robust set of documentation for usage. I needed a solution to quickly spin up docs with demos, navigation and code snippets. There is no shortage of options available for UI built in today’s popular front-end frameworks (React, Angular, etc.) but finding one for pure CSS proved surprisingly challenging.

I tested eight different solutions, including popular choices like Storybook (which advertises to have the ability to write docs for pure HTML – but any documentation I could find on this was for outdated legacy versions). None functioned properly without the built in structure of the frameworks. Only one proved effective for our needs: fabricator ( http://fbrctr.github.io/ ).

Fabricator allowed me to build out and structure docs flexibly with notes, code snippets and nearly full freedom of Information Architecture and demo construction.

Building the library

Armed with a documentation framework, I set out building the library in almost the same order as the Design phase, starting with the foundational style declarations and building upwards into more complex components, organisms, page sections and layout templates from there.

The rough order of build tasks went as follows:

• Base styles:
  • -Color Naming scheme
  • -Typography naming scheme
• Base elements
  • eg. Text Styles
• Components:
• Organisms
• Page Sections
• Modification Layer
• Documentation

CSS Codebase Snapshots

CSS Code Snippet – Color Variable System

CSS Code Snippet – Button Class Naming conventions

Screenshots of the CSS codebase.

Organizing the roadmap

Similarly to how I’d managed workload and visibility for the Design phase of the system, I built a new JIRA board for the CSS Library with tickets for each element to build and status columns for: to-do, blocked, building, built.

Communication and feedback

Just as the Design System Figma Library required buy-in and feedback from the Design team, the CSS Library would need awareness, comprehension and input from the frontend developers.

In order to get them involved (as well as loop in the Designers), I began hosting a series of bi-weekly presentations and discussions called the Frontend-UX Guild. In each installment, I’d give updates on the progress of the CSS Library, then discuss a feature or piece I was either struggling with or required feedback on.

An example of one of the earlier topics of conversation was how to structure the variable naming convention of our color scheme. There are many possible solutions that could work for this but I wanted to implement the Library in a way that was most satisfactory to the developers’ preferences (as they would be the ones using the system).

The guild brought about engaging discussions, suggestions and new ideas. One aspect I’m most proud of, was the opportunities the guild created to de-silo the very different working contexts of the design and development processes.

An example of this was highlighted in a discussion about spacing between elements. In a typical design work-flow, designers often spaced sets of elements with heavy usage of Figma’s auto-layout feature. The feature empowers a designer to set spacing to a specific pixel value between multiple elements on either a vertical or horizontal access. Although there are some overlaps of Figma auto-layout to CSS flexbox, they don’t quite map one-to-one, and this creates freedom for developers to interpret or set spacing however they see fit. Given that one of the goals of the design system was to reduce ambiguity of decision making, we decided to include a set of “spacing container” elements which would mimic auto-layout’s functionality.

CSS Library Documentation Site Screenshots

CSS Library Documentation Site

CSS Library Documentation Overview

CSS Library Documentation – Buttons

CSS Library Documentation – Button States

CSS Library Documentation – Page Tutorial

CSS Library Documentation – Grids

CSS Library Documentation – Text Elements

CSS Library Documentation – Cards

CSS Library Documentation – Listings

CSS Library Documentation – Notifications

CSS Library Documentation – Stepper

CSS Library Documentation – Flexbox

Screenshots of the CSS Library Documentation site with instructions for usage, code snippet examples, and tutorials.

Governance

With all the major components of the new system designed, Figma and CSS libraries built, the final piece was a governance process to allow for team members to suggest changes or request additions.

We developed a multi-prong solution for this. We adjusted the Design System Jira board with additional statuses to request changes. Designers would be able to make new tickets on the board for change requests. We designated an owner for the board who would be notified of any new change requests. If a request required, the team could deliberate on it async, via a dedicated Slack channel for the system. And if needed, we’d set a team voting session.

Requests ranged from small (like how a master component was structured) to adding new components altogether. In the first six months, we’ve averaged approximately two requests per month, with an average resolution time of less than a week.

APL Results and the future

The first version of the CSS Library was released in June 2021, marking approximately 1.5 years from initial start of the APL project to developer ready release. All of the major applications the Digital Department is currently working on are utilizing the new system.

Figma usage statistics show over 98% of current mockups are utilizing APL Library components and styles.

Additionally, marketing and communications department personnel have inquired about the design system and we’ve started presenting the results of our work to broader parts of the company.

In the future, we will look to iterate on the system, tracking usage analytics of the CSS Library from developers as well as keeping our feedback channels open and monitored.

Only time will tell the long-term impact and staying power of APL but for today, the future looks bright.