Front-End Development for an Open Source Government Site Redesign (Part 2)
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 Part 1 of this final post of the series, we examined our front-end development approach and critical components to this effort. In Part 2, we’ll be taking you through the various tools and technologies we used as part of this project to make our front-end development effort more cohesive and efficient.
Tools and Technologies
We utilized a handful of technologies on this project that allowed us to stitch together the various parts of the process from UX to design to front-end development. Some of these are shared below.
Jira
Jira is a proprietary issue tracking product, developed by Atlassian that provides bug tracking, issue tracking, and project management functions. We used Jira to catalog and track the tickets we used for our sprints, as mentioned in Part 1.
InVision
Using InVision (a digital product design, workflow, and collaboration tool), we were able to communicate design decisions to technical stakeholders. We put all of our page mockups in here so that the MassIT design stakeholder could add comments (with notes such as which patterns were optional, the format of the content, and if there were any associated behaviors). It, essentially, became the single source of truth for Velir and Palantir.net on how to convert the designs into working code .
Avocode
Approved designs were upload to Avocode (a tool used to convert Photoshop and Sketch files into web styles) to help accelerate the conversion of designs into code. This tool easily converted graphics into SVG icons, generated basic CSS styles (colors and font styling), and allowed us to take measurements and view the overall design without the added step of using Photoshop.
GitFlow
All of the code for the Mass.gov Mayflower project was stored in a GitHub repository using a GitFlow methodology. One of the great things about GitFlow is that it makes parallel development very easy by isolating new development from finished work. New development (such as features and non-emergency bug fixes) is done in feature branches, and is only merged back into main body of code when the developer(s) is happy that the code is ready for release.
The main advantages of using GitFlow were: 1) having separate branches to contain the code for each Jira ticket so that multiple tickets could be worked on in parallel, and 2) the ability to contain release tags. Since the new Mass.gov website (pilot.mass.gov) consumed the code from our Mayflower pattern library, we had to be very careful about denoting breaking changes. The release branches allowed us to put breaking changes into an isolated environment so that they couldn’t continue to be released.
SASS
All of the CSS for the Mass.gov project was generated using the SASS (semantically awesome style sheets) extension language. SASS extends CSS to make it more of a programming language by adding variables, mix-ins (methods), conditionals, nesting, and the ability to include files. This made it easier to organize our files and quickly re-use code instead of having to scatter helper classes (operations attempting to make code reusable) throughout the HTML.
SASS’s ability to include files is a huge advantage as it allowed us to break up our CSS into separate files matching the same atomic design structure created in Pattern Lab. For each pattern in Pattern Lab we created a corresponding SASS file to help keep the code organized, easy to find, and maintainable.
Since SASS allows us to use variables, it was extremely easy to make global changes. We’ve already seen this capability put to use by the Mass.gov government-to-government agency that wanted to re-color all the green elements on the main site with cranberry. We were able to reset the specific variable from green (#43956f) to cranberry (#680a1d), and we executed this global override in just a single step, instead of having to individually change multiple lines of CSS.
BEM
Since coming up with CSS class names is rather tricky to do, Velir adopted the BEM (Block Element Modifier) methodology. The basic concept of this methodology is that each pattern should start with one block-level item class (.block-name), and all related element-level items contained within that block should be given an element class (.block-name__element-name), using two underscores in between. If a pattern has variants, you should then add an additional modifier class to the block (.block-name — modifier) or to the element (.block-name__element-name — modifier), using two dashes in between.
The modifier should always be paired with the base parent or child class (.parent .parent — modifier) to make sure the modifier class only contains the code need to modify the element, thereby avoiding any duplication of CSS. With this method, we only needed to come up with a unique name for the block-level item; the elements within were based on their function (link, item, title, description, etc.).
As an added bonus, using BEM with atomic design made it much easier to break designs into patterns. The BEM method states that only block-level items can contain elements so if you find yourself wanting to create a class with nested elements (.block-name__element-name__element-name), you have most likely found a section of code that should be its own pattern. Using BEM, we’d give this section of code a new unique block-level class. Using Pattern Lab and atomic design, we would also move that code into a new file to be included as a partial. As new design elements were requested for Mass.gov, organisms, atoms and molecules would logically appear as the code was being written.
For example, as I was writing the Emergency Alerts organism, I also created the Emergency Header, Emergency Alert, and Button Alert molecules. Having to create the alert and button molecules was pretty obvious since they were a repeating pattern, but the header was unexpected. Since the header is composed of just a single data field, ‘title’, I was going to just add it as part of the organism. However, once I started creating BEM classes, I found myself wanting to add another element to the .ma__emergency-alerts__header class (.ma__emergency-alerts__header__title). The title contained a label (__label) and the text for the title (__title) so I broke this section of code off into a new molecule.
Using BEM with SASS and Pattern Lab made it very easy to determine when to break CSS into separate files and when to consider splitting a pattern into atoms or molecules, since each one should only contain one parent class.
Smaccs
In addition to BEM, Velir also used Smacss State Rules. A state is something that augments and overrides all other styles. This is particularly useful when an element has style variations of its end presentation. For example, an accordion section may be in a collapsed or expanded state. A message may be in a success or error state. To denote this, we add classes like ‘.is-expanded’ or ‘.has-error’ to trigger different styles.
For the Mass.gov project, one of the requirements for the Mayflower Style Library was the ability to quickly apply custom themes. As described above, SASS variables make it easy to make global changes, but occasionally, we also ran into the need to make more specific, constrained changes to a theme. For example, changing the background color on one pattern to be cranberry. To do this we chose to use the Smacss Theme Rules.
Smacss Theming states that for each pattern you should have two SASS files. The first file is the base file that contains the majority of the CSS styles. The second file is the theme file that contains the various color attributes, font weights, font-styles, and background images for that particular theme. For example, the base file would have ‘border-style: solid; border-width: 1px’ and the theme file would have ‘border-color: $c-theme-blue;’. When you want to apply a custom theme, you just need to modify the code within the theme file.
Gulp
Gulp is a a toolkit that we used for automating time-consuming manual tasks in the development workflow. A key goal of mine for this project was to simplify the setup process to involve as few steps as possible. Gulp allowed me to combine: SASS to CSS, JS bundling (including Bower files), SVG to Twig conversion, Pattern Lab generation, and starting a server (browersync), all into one gulp command that then watches for changes. As changes were made to the code base, Gulp would detect them, do the appropriate action, and then refresh the browser (or just update the CSS without a refresh) to show you the new code. What’s great about this is that anyone can do these few steps and have a page up and running without needing help from a developer.
Name Spacing
Given a project this large, we wanted to make sure that if the client decided to use a third-party plugin, our CSS and that of the third-party wouldn’t conflict. For this reason, we decided to add a namespace “ma__” (ma underscore underscore, where the ma stands for Massachusetts) to the beginning of all of our CSS class names. For example, the CSS class used for the page header was ‘.ma__page-header’. It is very unlikely that a plugin would also start their class names with ‘.ma__’, reducing the possibility of conflict between the different sets of code.
Tying it All Together
The front-end development of the Mass.gov project was a massive undertaking, involving collaboration between multiple vendors and many stakeholders to create a seamless user experience for 6.5+ million constituents. Utilizing the right approach, technologies, tools, and strategies contributed greatly to a successful redesign process. What makes this project even more rewarding is that it is open source, with the design and code available to everyone. (You can access it here.)
Have you worked on large, multi-vendor redesign projects, or government site redesigns? Do you have feedback and insights to share? We’d love to hear your thoughts and experiences. Please add to the discussion via the comments below or Tweet Us, @Velir!
Also, if you haven’t already, make sure to check out the first 2 posts in this series:
# 1: Designing for Usability, Findability, & Efficiency — Inside the Mass.gov Redesign
# 2: Applying a User-Centered Taskonomy Approach to a Government Site Redesign
