Front-End Development for an Open Source Government Site Redesign (Part 1)

Authored by Jonathan Dallas

As part of our blog post series on the Mass.gov project, we’ve already explored the UX and design aspects of the project. In this final two-part post of the series, we’ll examine our front-end development approach, and how we connected the various pieces of the Mass.gov redesign.

“The art of simplicity is a puzzle of complexity.” -Douglas Horton

In many ways, a website redesign is a lot like a puzzle. There are the individual pieces — UX, design, front-end development, back-end development — and each piece on its own is vital — but all of the pieces need to be connected properly to form a fully functional site and cohesive experience for site visitors.

As one can imagine for the Mass.gov project, this required a lot of communication between multiple vendors and stakeholders including MassIT, various state government agencies, Palantir.net (the agency that handled back-end development), and us at Velir (who took care of the UX, design, and front-end development). Shortly into this massive undertaking, we not only learned how to navigate the complexities of a government site redesign, we also discovered the subtle nuances of steering through the day-to-day challenges that exist in any large organization with multiple departments and stakeholders, each with their own priorities and expertise.

“Behind the seemingly simple web interfaces that make our lives easier, it takes professionals in a variety of disciplines, who are normally in their own silos, to break through barriers (organizational and operational) and come together to create what we use on a daily basis.”

Our Approach: Borrowing Concepts from Agile

Our approach for this redesign was unlike the more typical approach we’ve taken with other site redesigns due to a few key factors.

  1. The Mass.gov initiative had a pilot version of the new site (pilot.mass.gov) running live throughout the redesign process. This meant that instead of completely building the new site and handing it over to the client, we were updating the pilot site throughout the design and development process, so that actual users could test the different sections and provide feedback. This required a different approach as we needed to be able to iterate on completed sections as and when we received feedback. In terms of the coding, it required several extra steps to push out changes, which we’ll share in more detail below.
  2. Our approach was also influenced by the fact that it was unrealistic to expect immediate responses from clients and other stakeholders to questions or roadblocks that came up; real-world schedules and deadlines made instant changes impossible. Given this, and that there was no way we could put three different resources (UX, design, and front-end development) on hold every time we needed a response to something, we implemented a staggered approach instead. This meant that we would work on several different components and elements simultaneously, in an iterative fashion. Every time we received feedback, we would make the needed updates, hand it off to the next team, and go back to working on one of the other open items.
  3. To give you an idea of what the overall process looked like, for every new page (or content type) required, we would create tickets for UX, Visual Design (VD), Front-End (FE), and the Drupal Back-End (BE). These tickets would then be placed into two week sprints with UX and VD in the first, FE in the second, and BE in the third. With the nature of design work, we knew changes to the visual look and feel would probably continue to happen while the FE was being worked on, so we anticipated changes coming up and planned to just roll with it and update the FE ticket as needed.
Simple example of the breakout of different project disciplines across sprints.

This process required a bit more of a hand-off between stages, but we expedited the process by applying comments to the designs, and also held a few formal meetings to keep everyone informed. We added a design QA step to the front-end development workflow to give our designer the opportunity to review the completed sections and make sure they matched the designs, as well as to review the responsive behavior.

A huge win during this process came from our designer having great front-end chops. This allowed her to make updates directly in the code, instead of spending time recording the changes she wanted made. With the occasional issues that she needed additional help to resolve, I taught her how to make the changes instead of doing them for her. As you can imagine, this simplified the process tremendously and made updates far more efficient.

Pattern Lab

Having utilized Pattern Lab (the brainchild of Brad Frost of atomic design) on numerous projects before, we thought it would be an important tool to use for the Mass.gov redesign’s Pattern Library (Mayflower). Mayflower, the Commonwealth’s design system, is open source, which means that anyone can access and use it. This tool leverages atomic design to more efficiently build prototypes of Mass.gov pages from pre-existing patterns (Organisms, Molecules, Atoms) and then apply custom content (you can read more about its use on the Mass.gov project here).

Another advantage to using Pattern Lab is that it incorporates responsive design, which isn’t as efficient to demonstrate in mockups. This allowed us to test across a wide range of screen sizes very early on in the process. For example, one issue that came up was how the social share icons and header tags would stack on narrow-width devices. After reviewing this behavior, MassIT requested additional design elements to be added between them. This may not have been something that we would have caught with a traditional front-end development approach.

Drupal Integration

One of the biggest obstacles to building a pattern library is keeping it from getting stale. Most pattern libraries are built to be consumed as part of the website’s version 1.0 release, but after that release, new patterns and bug fixes are typically done on the website and not in the pattern library, causing it to become stale. For Mass Gov, it was very important to keep the pattern library up-to-date, with new patterns and bug fixes, since they were expecting it to be used by multiple sites. Keeping a pattern library up to date is usually a fairly challenging process, requiring all HTML changes to happen on both the website and the pattern library, so that the CSS and JS files can be used in both places. Since Mass.gov was being built in Drupal which has a Twig Theme layer, we decided to use the Twig version of Pattern Lab so that all of the updates could be made in Pattern Lab first, and then the Twig changes could be copied into the Drupal theme layer with a minimal amount of effort.

Once the Drupal work began, we talked with the Drupal team (at Palantir.net), and they helped us realize that this copy process could be automated. They could add a tool into the Mayflower repository which would look for release tags. If it saw a minor or patch release tag, it would automatically pull the new code from the Mayflower repository into the Drupal theme. Major release tags could also be automatically pulled, but they would need to be triggered manually to make sure the updates were properly reviewed and any breaking changes were fixed before being deployed. Breaking changes are those that are made in one part of a software system that may cause other components to fail, and occur most often in code that is shared by multiple applications. Automating this process made it much easier to make updates in Mayflower without having to also ask the Drupal team to make the same changes on their end.

Another thing we learned was how to make changes in a backward-compatible way. We got creative in our approach to avoid breaking changes; for example, we would check to see if an old variable was there, and point the new one to it, to make the changes work.

Pull Requests

To ensure that the code going into the dev or release branches was built correctly, we used pull requests in GitHub to do code reviews before allowing the code to be merged. This process utilizes a gatekeeper role to manually make sure the quality of code is good. When a pull request is made, it automatically contains what code changes are being made, along with an area for the creator to describe those changes and why they are needed. The reviewer can then easily scan the changes to the code to make comments about requested changes, or they can approve and merge the code into the desired branch.

An added bonus to this process was that since I was the only official front-end developer assigned to work on Mayflower, all of my pull requests were assigned to a front-end developer on the Drupal team at Palantir to review. This allowed the Drupal team to be better prepared for the changes that were coming through in every subsequent release, and I also became more aware of how to write code that worked better for them.

Tools and Technologies

In addition to what’s mentioned above, we utilized a handful of various other technologies on this project that allowed us to stitch together the various parts of the process from UX to design to front-end development. We share some of these tools and technologies in Part 2 of this post.

In the meantime, if you’ve worked on large, multi-vendor redesign projects, or government site redesigns, we’d love to hear your thoughts on your challenges and experiences. Please add to the discussion via the comments below or Tweet Us, @Velir!