Design System

Handshake

Establishing a design system and research repository for the Code for America Brigade network.

What was Code for Chicago and Handshake?

A volunteer brigade building tools for the causes it served.

Code for Chicago was a volunteer-run civic tech brigade under the Code for America Brigade Network. In my time there we functioned like a pro bono tech consultancy. Sometimes it didn't make sense to put more volunteers than necessary on a client-facing project, so we kept a couple of internal projects going where they could still make a meaningful contribution.

Handshake was one of those internal projects.

The Problem

The website had no shared standard to build from.

The site was originally built in Jekyll, a stack that didn't match what most incoming volunteers actually knew how to work in, so we began transitioning to Gatsby, a more popular tech stack.

Additionally, without a documented design system, every new designer or developer who joined made their own judgment calls, and the site drifted a little further from itself each time. I pitched to establish a design system so if we made new pages, they would operate from the same design principles.

There also wasn't a standard for how the brigade presented itself so I started wondering whether we could build a system we could pitch to Code for America as a toolkit for new brigades. In lieu of having to prop up their own website, they could copy our repository and design system as a start. This way their capacity would be leveraged to make partners instead of working on a marketing website.

I made the case for treating this as more than internal cleanup.

The website had been an ongoing internal project we assigned to volunteers whenever we couldn't find a better fit elsewhere. When I pitched Code for America on building a real design system and research repository for the brigades, they were on board.

Building the System

We broke the site into components before we rebuilt any of it.

I identified what already existed on the site and broke it down using atomic design, turning every gap into a ticket. From there we built up: smaller components first, then larger patterns.

I established the grid and responsive breakpoints myself, redesigned the logo, and worked directly on components like the block quote, hero banner, and forms. Everything got documented twice: in Figma for the spec, in Gitbook for how and when to use it.

An additional pitch for Handshake was having it double as a research repository. I assigned our research team to run usability tests and persona work, initially to understand our own volunteers, but the findings held up as a reference point for how any brigade in the network might think about the people building their sites. I turned that research into tickets and direction for the design team, and reviewed component work before it moved forward so what shipped stayed consistent with the system.

Getting It Live

Migrating the site meant sequencing my work against the developers'.

The team had already decided to move off Jekyll onto React and Gatsby. Making that work meant coordinating sequencing with the Tech Leads: finish migrating the existing content first, then hand developers design system component tickets once the design side was actually ready for them.

Outcome

The system worked. The brigade it was built for didn't last.

The brigade network wound down before the toolkit pitch went anywhere beyond us, but the system did its job while it existed, and I shared it with other brigades before the door closed. I'm proud of the work itself, the discipline of breaking the site down, documenting it twice, keeping a rotating team consistent, even without a lasting outcome to point to.