Timeline
March 2019 – July 2021
My Role
  • Strategy
  • Research
  • Product Design
  • Engineering
Tech
  • Figma
  • React
  • React Spring
  • Storybook
  • TypeScript

Background

Cityblock is a health company which got its start within Google’s Sidewalk Labs. Teams of clinicians and other health professionals provide in-community care to people on Medicare and Medicaid to improve health for an often-neglected population.

Andre, a Cityblock member, tells his story. Via Cityblock on Vimeo, 2023.

To support care teams and the members they serve, Cityblock builds and maintains a tool called Commons. I joined Cityblock in February 2019 as a Product Designer and recognized a need for a more systematic approach to design. Over the following two years, I built and expanded a design system in Figma and React. I named it Commonplace.

The Challenge

Cityblock was less than two years old, but Commons already offered a sprawling set of features, including: tracking member status, charting member acuity, coordinating member outreach, storing and editing core demographics, viewing health history, scheduling events, managing tasks for individuals and teams, creating and administering health assessments with automated scoring, texting members… all that, and more planned.

All of these features converged in an interface that looked like this:

The Cityblock dashboard. There are many different styles, colors, and
fonts.

The appearance of Commons when I joined Cityblock. Here, in the right-hand drawer, a user is composing a progress note about the current member. The varying colors, typography, and hierarchy make the interface difficult to understand. All member data displayed in this case study is notional.

Although there were some underlying commonalities and shared language throughout the product, the design was not scaling to meet the needs of its users or developers.

A lack of systemization was leading to longer development times, more time spent on undifferentiated work, more bugs in the product, and a user experience that was inconsistent and confusing. These problems would only worsen as Cityblock grew.

Mapping the Territory

Together with Cityblock’s Director of Design, Neves, we catalogued the available views. I conducted a product audit, clicking through and taking screenshots of every view, dialog, drawer, and dropdown within Commons. The images were then organized into folders for future reference.

A product audit. We captured screenshots from every corner of Commons and organized them in folders corresponding to the app’s information architecture.

The product audit helped us understand the current state of Commons, and it ushered in an essential archival practice for the future. Throughout my tenure at Cityblock, I would continue to catalogue product interfaces at least once a year.

Following the product audit, we created an interface inventory, collecting all variations and permutations of each component and displaying a collage of those permutations on a large poster board.

A black foam board with several sheets of paper pinned to it. Each sheet of
paper displays a component name and a collection of variations on that
component observed in the product.

The interface inventory. The product audit screenshots were used to create a collage of each component’s variations. How many header styles can you count?

This inventory allowed us to more easily spot inconsistencies and discuss how best to resolve them across the system.

Laying Foundations

Once the interface inventory was complete, we focused on design foundations—typography, color, and spacing. All components rest on top of these three primitives, and we wanted to get the essentials right.

Typography

Care teams at Cityblock are given small Chromebooks to take with them around the city. They use their Chromebooks to access Commons in many locations: the office, at community hubs, in members’ homes, and in their car or on the subway.

As we laid out a typographic scale and compared different typefaces, we made sure to test text on the Chromebook’s low-DPI display in a variety of real-world, less-than-ideal lighting conditions, in order to ensure that Commons was legible in every setting.

A screen within Commons

Low-contrast typography within Commons. Many views contained small, light text which was difficult to read under ideal conditions, and practically impossible in others. All data is notional.

With Cityblock’s brand designer, Minji, we tested various typefaces for the product before landing on Graphik for its legibility and understated friendliness. All text colors within the new design system would adhere to WCAG AA or AAA contrast ratios.

The Commonplace typographic scale, using the font,
Graphik.

The typographic scale. The base unit is set to 16 pixels and most header sizes scale up from there using rem. After experimentation, we decided to break this scale for the body size (15 pixels) and small text (13 pixels) in order to maintain medium-high data density.

Color

When considering colors in Commons, we prioritized pure function, accessibility and contrast, relation to the brand, and coherence as a whole.

I also examined the use of color in film to portray two separate settings—the hospital and the home.

A collage of various hospital settings portrayed in film and
TV.

A collage of various "home" settings portrayed in film and TV.

Colors of the hospital, and colors of home. What feelings do these scenes evoke?

The hospital blue-greens are distinctly clinical, down to the robes worn by patients and doctors, and feel somber and sterile. “Home” tones, in contrast, emit a warm, welcoming glow. I wrote at the time, “Cityblock should feel less like the hospital, and more like home.”

This led to guiding principles:

Guiding Principles for Color in Commons

  1. Color gently. Opt for soft, subdued tones. Avoid highly-saturated, electric colors.
  2. Use high contrast elements sparingly. What is the one action on any given view that deserves attention?
  3. Skew warm. Do not tint neutrals blue.

And the resulting palette, defined as matching Figma styles and CSS variables:

The Commonplace color palette with matching variables in
CSS.

The color palette. Colors are arranged along a spectrum from 100 (light) to 900 (dark). Some colors are aliased with a semantic name, so developers don’t need to remember that icons are --color-neutral-600. They can just use --color-icon.

Spacing

We agreed to use an 8 pixel grid for all components, and we agreed on specific fixed widths for sidebars while leaving the rest of the app responsive to scale with the browser.

Building Components

Once foundations were in place, primitives were set up both in Figma and as CSS Variables in the codebase, and we were able to quickly and easily replace all existing hex codes with new color variables, replace existing padding, margin, widths, and heights with the new spacing scale, and swap out the typography.

Then began the long and steady process of building and replacing components one-by-one. Create a new Button. Test it. Swap out all existing buttons and delete all existing styles. Merge in the changes. Pick a new component, rinse and repeat.

Components displayed in Figma and in code.

Commonplace components. Each component in the codebase included unit tests, a Storybook story, and JSDoc comments for each prop in order to provide in-context documentation within VS Code.

Component work took place over the course of many months, alongside other feature work I was involved in. It took place largely independently, although I continued to collaborate with Neves for visual and interaction design feedback, researchers like Amber and Taylor for user insights, and engineers like Brennan, Aster, and Craig for code review.

We chose an incremental approach—rather than building and shipping an entirely new design system all at once—in order to maintain forward momentum, bug test along the way, and enable new features to be built with new components as quickly as possible.

Outcomes

By January 2020, most views within Commons used Commonplace components. Responses from engineers and care team members were overwhelmingly positive. Bug reports decreased, new features became easier to build, and engineers got to spend more time on differentiated work and less time fiddling with CSS.

Despite the addition of new components, several thousand lines of code had been deleted since the start of the project due to the reusability and modular nature of the design system—a meaningful reduction in complexity and technical debt.

The action plan in Commons before the introduction of Commonplace. The action plan in Commons after the introduction of Commonplace.

Member action plan, before (early 2019) and after (early 2020). More information is available at a glance, without drilling down into cards and accordions.

The member table in Commons before the introduction of Commonplace. The member table in Commons after the introduction of Commonplace.

Member table, before (early 2019) and after (early 2020). We aimed to main medium-high data density, helpful for our care staff, while making the UI feel more approachable and calm.

Around this time, I gave a company-wide talk about design systems, a concept which was unfamiliar to many people outside of the tech team. There was palpable excitement over seeing the drastic comparisons of before and after screens.

I would continue to contribute design and code toward Commonplace until my departure in July 2021.

Reflections

Care teams at Cityblock do difficult, meaningful work, and it’s essential that the technology we build for them respects their time and energy. I’m proud of the way I was able to help transform Cityblock’s approach to design and engineering, and (hopefully) reduce stress for our hard-working care teams.

Health tech is a complex space, and I still see dozens of ways that Commons could be streamlined. A design system is only as strong as the features it’s used to build, but where a design system ends and product features begin isn’t always clear. There is always more to do.

As I write this, in February 2024, I’ve just returned to Cityblock to help level up design systems again. After 3 years’ absence, the system foundations I put in place have held up well. Some areas have flourished, others have remained the same, and a few weeds have sprouted, but it’s a wonderful feeling to see the work you put so much effort into continue to endure.