Employer
Development Team
- Webmaster and UI Specialist (me)
- Senior PHP Developer
- Senior Java Developer
- Team Manager
- Department Director
What I did
- Product Design
- HTML/SCSS/JavaScript
What I used
- Atom
- Gulp
- Photoshop
The Problem
My team at City Hall built more apps than we could maintain.
The two back end developers had each shipped over a dozen internal tools for a wide range of use cases, including a database of public board members, problem reports, road project management, and City Hall’s internal staff directory.
As our backlog of projects grew bigger and bigger, we needed to ship more apps in less time.
Before the refresh. What an internal tool typically looked like before I joined the team.
Project Requirements
- Visual refresh. Update the look and feel of City Hall’s internal tools without increasing the workload for the two back end developers.
- Treat all developers as equals. Make sure code samples and documentation deliver equal value to the PHP developer, and the Java developer.
Starting with a fresh coat of paint
I focused on a visual refresh of elements that were common to the apps that were already built.
After the refresh. Many of the apps I saw were not nearly as data-dense as the enterprise training management app I had worked on at my previous job, so it made sense to give these apps some visual breathing room. The background image appealed to civic pride by featuring a beloved local landmark.
Going responsive, one small opportunity at a time.
Parking enforcement officers needed to track broken meters and the work orders to repair them—right from their City-issued phones.
I seized on an opportunity to help the team do something it had never done.
One small step for the library, one giant leap for the team. By December 2014, the team hadn’t worked with responsive design. By adding responsive patterns to the library, I enabled the developers to support both phones and desktops from the same codebase, without increasing their workload or forcing them onto a painful learning curve.
Making the pattern library themable
My team proudly makes its open source software available for other cities to use, so our UI needs to be adaptable to their branding.
Dogfooding our theme system. We started an un-branded baseline theme (top), and built two themes on top of the baseline (left, right), to demonstrate what was possible. The theme system was flexible enough for other cities to completely replace our branding and information architecture with theirs—and add their own branded components to their theme.
Generating code samples for different tech stacks.
My team consisted of two specialists: one PHP developer, and one Java developer. The design documentation and code samples needed to be equally valuable to both of them.
I used Gulp to build stylesheets with node-sass, and templated HTML with Swig (before Swig was orphaned). I handed off HTML, CSS, and JS to the two backend developers, who adapted the code to work with PHP and Java.
Planning for growth with semantic versioning
I established a workflow with the following steps:
- Build new apps using the bleeding edge version of the pattern library.
- When a new app is ready to start user testing, ship a new release of the pattern library, and update the app to use the new release instead of the bleeding edge version.
- Use semantic versioning to communicate expectations about backward compatibility.
Results
Outside feedback was mostly positive.
Shortly after we unveiled the new design in the Staff Directory app, one high-ranking person from another department commented: “I usually hate everything you guys do, but I like this. This is good!”
Internal reception of the pattern library was mixed.
The theme for internal tools fulfilled the goal of implementing a refreshed look and feel, without adding to the developers’ workload.
Although the initial goal was fulfilled, my goals for growing the library were unmet. The team didn’t invest in adding new patterns after the initial introduction. When gaps in the pattern library came up, developers did what they had always done: Design and implement a solution independently—without input from a design specialist, usually with an off-the-shelf jQuery plugin.
The theme for the City website helped me win buy-in for more challenging design projects.
Parks and Recreation Department landing page. I was able to push back against hesitancy to do custom design for one department by arguing that if we add a pattern to Factory Number One, this design work won’t be “playing favorites,” it will be a value-add for the whole organization.
What I learned
When getting buy-in for a design system or pattern library, lean in to the productivity benefits with the engineering manager.
At the time, this was a big change for the team. There was initially some resistance from individual developers to working with a UI library like this. However, once I convinced the engineering manager of the productivity benefits, it was much easier for me to proceed.
What I would do differently
Expand on documentation.
Demo pages are good. Demo pages and documentation is better. These days, I recommend that pattern libraries inform the team about:
- The maturity and API stability of each component.
- Version history.
- Guidelines about when—or when not—to use each component.
Use Web Components to make the same design patterns available to different tech stacks.
Instead of using Gulp and static HTML to make the same design patterns available for different development platforms, I would recommend a front-end componentization strategy. That might be using something like React or Vue, or it could be using Web Components—potentially leveraging a library like Lit or a compiler like Stencil. It depends on the team.
