The idea for documenting the Design System came about early on in my internship when I noticed that I kept running into the same road bumps during projects. Whenever I got to the design phase, I’d always bombard my manager with design systems questions, like where to find certain design work on Figma, and which styles for a component to use. There was no documentation I could reference, hence the endless Slack messages.
This lack of clarity was taking up my time working on the project, disrupting my manager, and interfering with the consistency of user experiences being built on the site. So, I decided to take it upon myself to fill this gap in ShipHawk’s design culture.
I first decided to do some research and analyze the design systems of high design maturity companies: Shopify Polaris, Workbench Gusto, Atlassian Design System, IBM Carbon. From these design systems, I got a sense of the tone and language being used, how components are properly named, and how strong design teams established guidelines. I noticed that they all followed a similar structure of Foundations, Components, Patterns, etc. and decided to adopt that as an outline for the content.
After getting an idea of how to structure the documentation, I started to hone in on the audience that would be using this. At ShipHawk, I expected Product Designers, Engineers, and Product Managers, and Technical Writers to refer to this. I set up meetings with members of the Product Team to learn about their needs and priorities and how I could address these with the documentation.
As the only ShipHawk designer at the time, I didn’t have any other designer to consult with, so I relied on my own experiences when thinking about how future SH designers could use this documentation. I thought about the gaps in knowledge I had and what resources would’ve been helpful as a new hire. Later on, I connected with Amanda Crissman, a Senior Product Designer at AppFolio that had experience building Design Systems. From Amanda, I got to hear about her first hand experiences in cross-team collaboration when crafting a Design System and Product Team workflows.
The Product Team’s unique insights led me to coming up with 3 main goals that guided me for the rest of the project:
Due to limited development resources, it was important to prioritize just documenting what was currently in our design system over revamping.
As Designers, we always emphasize the importance of creating a seamless user experience for our users, and this case isn’t any different. Here, the users are ShipHawk designers, who need to be able to navigate this documentation easily.
Design system documentation isn’t just about recording the current components and workflows have, but also how to maintain the design system. As the company continues growing, so will the system.
Keeping these goals in mind, I dived into auditing the site to take note of all the components. To organize everything, I created a spreadsheet to track the components and their variants. I also used this to cross reference what components had already been built in Figma and to determine what needed to be added.
Standardizing was one of the most difficult parts of documentation. There were several instances where components had different styles and even conflicted in use-cases. This was really concerning because having consistency is essential to providing a reliable user experience for our users. Trying to settle these inconsistencies was tough, and there was a constant weighing of user experience and what was the best use of developer time.
Buttons
One of the many components I struggled to standardize was Buttons. Across the SH site, there didn’t seem to be any rhyme or reason behind the choice of color and button type. How I decided to approach this was to first list out all its variants in the spreadsheet. To help in narrowing down on some guidelines, I took note of the contexts they were used in (e.g. pages with modals, types of actions, etc.) and tried looking for common contexts and use cases among similar buttons.
The platform that I ended up documenting on was Confluence, a web-based wiki that ShipHawk teams in various departments use. I worked with our Technical Writer, Michael, to write the content in Confluence. While I focused mainly on Onboarding Resources and the Design System, he added content for User Personas, UX Writing Guidelines, and an Upcoming Projects list.
When writing out the documentation for Buttons, I laid out the content in different sections: Color, Button Type, Guidelines, and Content. I thought the best way to represent the different styles and cases on Confluence was through an organized chart that would be easy to quickly look through.
The other Component pages took on a similar layout of a table with variants and the contexts they’re used in, style guidelines, content guidelines, and resources.
New Designers can better familiarize themselves with the Design culture at ShipHawk, and how workflows and collaboration amongst the Product Team looks like. The site map, pictured on the right, includes links to the corresponding Figma page, allowing for easier reference to previously designed mockups.
Refer to guidelines and best practices to create consistent user experiences across the ShipHawk site. By familiarizing themselves with where and how components are used, Designers can save time designing and reduce any handoff friction.
Use this decision chart as a guide when deciding when to add to the design system. The goal for this is to help Product Managers, Designers, and Developers align in maintaining the documentation, keeping consistency, and avoiding any unnecessary additions.
This guide will be used across ShipHawk's Product Team, and for onboarding new front end engineers as well as designers who can get to know SH's Design philosophy, standards, and resources.
of documentation drafted for 2 scrum teams
standardized and documented on Confluence
in design productivity
When I started this project, I was daunted by the amount of work that needed to be done, but I knew this would help lay down the roots of ShipHawk’s growing Design culture. With this new documentation, future designers that join ShipHawk will have something to reference to in order to craft consistent user experiences. The Product Team and Engineering Team can better align on design, making more efficient collaboration and productivity.
Due to time and resource constraints, I mainly focused on documenting the design of components, patterns, etc. of what was already present rather than changing anything. When ShipHawk does have the bandwidth to flesh out its design system, I would focus on the following:
There were many UI issues that I wanted to tackle and fix but didn’t have the resources to. As difficult as it was to let go of these problems, I knew that it was more important to create a strong foundation that future designers could continue building on top of.
Not having another designer to collaborate with on this project made me turn to other people in Product. Talking to Engineering made me think about design system maintenance, and getting advice from a Senior Product Designer with design systems experience allowed me to consider exploring how this maintenance would look in practice.