Case Study: Design System Guide
In 2025, I helped a university better use their new website's design system by building comprehensive, user-friendly documentation.
THE CHALLENGE
My team at a higher education marketing agency specialized in building new websites for colleges. But while the design systems we provided our clients were visually compelling, at 40+ components apiece, they were often too complicated for our clients to effectively use.
College websites are often tens of thousands of pages, and as universities typically have limited web teams, the people responsible for adding content to their sites are faculty, administrators and others without any specialized knowledge in how to work in a Content Management System (CMS). With our client contacts overwhelmed and frustrated at this critical moment when we handed over the new website, this problem was having a significant negative effect on client sentiment and thus on their desire to continue working with our agency going forward.
My team needed a way to translate our design documentation from an internal tool to aid in web development into a simple, client-facing explainer that users with minimal technical knowledge could reference to generate web content at scale.
MY ROLE
As the team's first ever content designer, I worked with UX and UI designers to produce clearer component descriptions for the design systems they had created, as well as to lay out the guide in an easy-to-use manner to best serve our audience of client web content creators. I also worked closely with our development team to ensure the components were built to match the requirements I had documented and to alter those requirements as needed.
THE PROCESS
Before I joined the team, the design system guides my colleages put together looked something like this:
Two excerpts of a lengthy single webpage containing the component library for a university design system
After identifying a variety of limitations with the old layout, our team together decided on a variety of improvements we wanted to make to the next iteration of this guide, starting with being more intentional about the instructional copy it included. I identified three categories of information to include alongside each component:
-
a description of what the component is
-
the parameters for the all fields, including which are mandatory and the recommended character limits for all text fields
-
the use cases for when a web editor should include the component on a page
Then I put together an Excel document with this information for a UX designer to incorporate into the new guide along with examples of each component. Here's a portion of what that document looked like:
A portion of an internal document laying out the instructional copy to include in a design system guide
While an improvement in many ways, this approach to creating a design system guide still had a variety of limitations:
-
Because the components had already been developed before I wrote this copy, they included counterintuitive field labels—written by a developer, not a content designer—that I then needed to include in the guide so that users would be able to understand what they meant.
-
The spreadsheet method meant that I was writing content for all three categories for every component, even when it wasn't strictly necessary—such as for commonly used web components where the use case was self-explanatory.
-
Because I wrote the copy in isolation from the sample components, I wasn't able to consider the entire user experience of reviewing the guide as a cohesive whole.
Ultimately, it became clear that producing the design system guide at the very end of the web development process was insufficient.
The design system guide needed to help shape the design system, not simply record it.
THE SOLUTION
Working with our project management team, the design team ensured that we would produce the design system guide before the web development stage of our redesign process, rather than after. By creating the guide in Figma rather than directly in the CMS, we could then optimize the entire experience, with copy and design in sync.
When we began our next website redesign, I worked closely with our UI designer to ensure that components and their fields had logical names, that mandatory fields and intended character count limitations were considered during design, and that every component had all the variants it needed.
We also innovated on the overall design of the guide, building a homepage that included images of each component—so that users would not need to remember their names—and logically organized categories. I ensured that the sample components on each page had their fields labeled so that users would not have to guess what was the "headline," "description," and so on.
Here are a few sample pages from our new version of the design system guide:
Four pages from a design system guide produced for a client to go alongside their newly redesigned website
THE OUTCOME
While we were not able to collect data on utilization of the new design system guide compared to earlier versions the team had produced for other clients, feedback from this client's web team was extremely positive. As our primary developer contact put it:
"The sample guide covers pretty much everything that we could hope for. Thank you. Everyone loves the general direction and unanimously agrees that the new site is lightyears ahead of what we have now."