Urban Institute’s Data Visualization Style Guide: A living document
As a data visualization developer at Urban, our style guide is always one of my open tabs. I refer to it constantly to copy hex codes or confirm font sizes. I regularly share it with colleagues to help them create their own graphs or to explain how various style decisions are consistent with our brand identity.
The style guide defines uniform design and layout for charts and graphs across all our platforms, but its rules are not set in stone. Style guides should be living documents that evolve over time.
Members of Urban’s Communications team developed our data visualization style guide in 2015. It contains precise definitions for the style and layout of chart elements, as shown below.
In addition, there are sections on Urban’s color palettes and font styles, conceptual guidance about how to determine which chart type fits your data, and some discussions of common problems with pie charts and maps (as well as possible solutions).
In this post, I talk about how we currently use the guide, how it’s changed over the past three years, and changes we have planned for its future.
Urban’s Style Guide(s)
The data visualization style guide has served as a template for other style guides, specifically the Tax Policy Center’s (TPC) own guide. Unlike Urban’s other centers, TPC is a joint venture with the Brookings Institution, and as such has some of its own distinct style guidelines (fonts, colors, logo, etc). And while it’s not directly related to data viz, our editorial style guide was also built from the same template — a nice shortcut for web development!
All three of these documents are hosted in public GitHub repositories (Urban, TPC, and editorial). You can see from the main guide’s commit history that we’ve made a handful of small changes to it over the years. We’ve added guidance (such as a note to avoid using blue to represent men and pink for women), updated links and contact info, and done other small bits of maintenance. But the largest developments have been the creation of new processes and templates based on the style guide.
Style Processes and Templates in R, Excel, and on the Web
Among the various software tools used here at Urban, many Urban researchers use R for their statistical analysis and for their graphics, they use ggplot2, the gold standard R library for most types of data visualization. In 2016, building on earlier work I did at the Sunlight Foundation — creating ggplot2 style scripts based on Sunlight’s data viz style guide — I wrote a very bare bones R script to create Urban-styled ggplot2 graphs.
Aaron Williams, a research analyst at Urban, has taken ownership of these scripts, and has done tremendous work updating (or really, rebuilding) them to add features and keep abreast of changes to the ggplot2 package.
While the R output is not 100 percent publication ready, it is much closer to Urban style than default ggplot2 output. Below, you can compare a chart created using the ggplot2 theme with one created in Excel, which fully conforms to the style guide.
You may notice a handful of differences. For example, in the R chart, the y axis label is not positioned above the axis, the title is not left aligned with the axis ticks and is a bit too low, and the Urban logo is not fully styled.
These changes are quite difficult to make programmatically in R, especially in a theme that applies to arbitrarily complicated charts. The R output is ready for informal use (such as internal presentations) or can be quickly edited to perfectly match style guidelines. ggplot2 graphs can be exported as pdfs, where the individual chart components can be edited in Adobe Illustrator, then exported as publication-ready graphs. In practice, the simple chart above would not need to be made in R, it could quickly be made or remade in Excel.
Jon Schwabish, an Urban Institute senior fellow, has developed solutions for building Urban-themed graphs in Excel. The overwhelming majority of charts Urban publishes (in both standard publications and in blog posts) are created in Excel. Excel is installed by default on all Urban computers, and most chart-creators (researchers and editors), are familiar with it.
We developed our style guidelines so that Excel could create publication-ready charts that didn’t need to be tweaked or modified in any other program. While it would be a tremendous amount of work to update fonts, colors, spacing, and other styles by hand for every chart, Jon built a point-and-click Excel add-in, comprised of a series of macros, which can create a production-ready, Urban-styled copy of any Excel chart for most use cases.
Urban’s Data Visualization team spends most of its time building interactive charts for the web, primarily using the D3 JavaScript library. In most cases, these are highly customized charts and other visuals, which means we aren’t able to use the same type of templating we use when developing more standard charts in R and Excel. That being said, we still conform to Urban guidelines for color, font, and other design elements.
Simpler charts (like bar charts and line charts) can also be made in D3. D3 is highly customizable, and can perfectly match Urban standards, but creating charts is labor intensive.
In R or Excel, a single button or function can build a bar chart, but in D3 code, each individual chart component must be explicitly built — there’s no inherent D3 “bar chart” object, just a collection of line, text, axis, and rectangle objects. We build standard chart types in D3 when they require interactivity, but in other cases Excel is much faster.
Plans for the Future
In the coming year, we plan to speed up the process of building D3 charts (both standard and custom chart types) by developing a variety of templating tools for web-based graphics. For highly customized charts, this might mean using CSS or CSS preprocessors like LESS or Sass to generate more universal styles. Preprocessors make CSS more reusable through features like the ability to define variables, instead of repeating values in many locations (no more copy and pasting hex codes from the style guide website!).
For more standard chart types, we plan to develop even more robust styles. With more modular and reusable JavaScript and standardized CSS class names and id’s, we can create more universal style sheets and interactive chart templates.
In addition to these new CSS and JavaScript templates, we plan to update the style guide to reflect lessons we’ve learned since its launch. Many of these changes will be similar to the small tweaks we’ve made over the years, but with a more systematic approach. For example, Urban charts only include tick marks on the x-axis when it represents continuous (as opposed to categorical) values. So a line chart gets tick marks, while most bar charts do not. The guide should make this explicit and the example charts should be updated.
We also want to expand on the “Color” section of the style guide. While we aren’t altering our brand colors in 2018, we do want to include a more robust discussion of how we currently use various colors. For example, we include a light grey (#d2d2d2) as one of our categorical colors. We normally use this grey to deemphasize elements that aren’t the focus of the graph. Although we hint at this in the style guide, it isn’t reflected in the example images or discussed in enough depth.
We also plan to take another look at our style guide in 2018 with an eye towards accessibility — that is, making our graphics legible and comprehensible for all users, including those with disabilities. In her 2017 talk, “Why Does Data Vis Need a Style Guide” Amy Cesal discussed her work on the style guide at the Consumer Finance Protection Bureau (CFPB), and its focus on accessibility. (Amy also helped develop the Sunlight Foundation style guide linked above as well. Data viz design is a small world.)
The accessibility section of the CFPB style guide discusses color and “alt tags,” the text a screen reader sees for any given image. We plan to update our style guide along similar lines, and will be sharing our process and results on this blog.
The data visualization style guide is a living document. As our team grows and learns, we will continue to adapt and update it, striving to make our charts more legible, more beautiful, scalable across more platforms, and accessible to all.
Want to learn more? Sign-up for the Data@Urban newsletter.
An earlier version of this story included a sentence linking to an unpublished post. That sentence has been removed (corrected 3/21/18).
