Creating a Collaborative Style Guide for Designers and Engineers
This post was co-authored by Ying Wang, Associate Product Designer with iOS Engineers Daniel Vancura and Phill Farrugia.
Creating and using a typography style guide has always been a challenge for designers and engineers. Have you ever struggled with text style naming conventions? Have you ever felt it’s hard to digest which styles are used where? Have you ever experienced difficulties updating or adding type styles when building an app? That’s what we experienced too!
One of the systems we created in response to this was a flexible, collaborative, and scalable typography guide which we used in working on a new app for one of our partner’s brands. After we successfully launched that app, the partner wanted us to reuse the app’s framework for their additional three brands but with different branding including text styles, colors, icons, and empty state illustrations. We needed a systemized style guide to adapt the different typography themes across all four apps, as well as reuse the code we already built for the first app. Here we explain how we built it and how it benefits designers and engineers.
The Concept & Structure
The core concept is:
- Divide each text style into two parts: Font Style and Color Style.
- Put all the font and color styles in rows and columns to create a grid layout that maps out text styles (In the grid there are a maximum amount of possible text styles, but you only mark the ones in use).
- So, the text style = font style (row) + color style (column).
Why is a text style divided into font style and color style?
A text style contains font, weight, size, letter spacing, line spacing, and color (Alignment is also a common attribute, but it’s more context related and would be more practical to set up in code). Many text styles across an app share many of the same attributes but vary in color, so we separated them into two groups defined as “font style” consisting of the font, weight, size, letter spacing, and line spacing attributes, and “color style” as the color attribute to map out all the different combinations.
What’s the benefit of using a grid?
We chose to use a grid for a series of reasons. The modular system gives the flexibility to add styles. For example, a font/color style can easily be added by adding a row/column. To mark a text style, just write in the cell with the font and color style combination that is wanted. Automatic naming conventions give each text style a unique name from its row and column number. The grid also provides an easy way to visualize and organize the text styles in use. Engineers benefit by looking at smaller sets of data at once, making it easier to implement through protocols by only defining a few aspects per theme.
How Designers Create the Typography Style Guide
Now that we’ve shared the concept and structure of the typography style guide, we will explain how a designer can create one for their own project.
The image above demonstrates one of the processes we use to implement text styles. We use Google Spreadsheet to create the typography style guide, and use Zeplin to show what styles are used on each screen. The approach we take using Google Spreadsheet and Zeplin can be adapted to many other tools for the same result.
Start by adding a text style in the style guide sheet.
- Click on the text layer in Sketch to see what the attribute values are.
- Add the attribute values in the style guide sheet (in this example, font and weight are in different columns, but they can also be combined into one as shown in the gif).
- Mark the combination of the text style.
Upload screens to Zeplin and mark the text styles for the engineers.
- Select the screen in Sketch and choose Plugins > Zeplin > Export Selected Artboards.
- In the popup modal, click “Export” to complete the upload.
- Once the screen is uploaded on Zeplin, double click to enter the screen, select the text layer, and mark the text style (Once the text style is marked, Zeplin will recognize all the other text layers with the same style and name them).
How Engineers Benefit From the Style Guide
As mentioned in previous sections, we implemented an approach for creating style guides that give a few parameters in terms of color and font attributes but have a great impact on the visual appearance of the app. In this section we’ll take a deeper look into how this affects the engineering side and how we translated this style guide to code in an iOS app.
While the more common approach is to create a list of different styles, we find that engineers benefit from the systemized style guide due to the smaller sets of data that make it more digestible, and in implementing through protocols by only defining a few aspects per theme instance (what is font size XXL, what is color in column 1, etc).
Implementation Using the Style Guide Approach
The challenge of creating multiple apps in a single code base led us to create this streamlined approach. What we achieved was the ability to compose new styles out of already existing sets of attributes used on other styles. We could add and remove new style compositions when needed. If adjustments to a certain UI element became necessary, we could just replace the row or column with a combination of rows and columns that we already had and we’d be done.
Breaking the implementation of the style guide into smaller pieces also made maintenance a lot easier. Since our changes were sometimes affecting multiple styles at once, it was easiest for us to just tweak a single parameter in one of our structs and the overall appearance of the app would change. A good example of this was the font size we used for the app: While it initially was the same on all apps, we had to adjust it for two apps due to different fonts being used. Since we only had a few rows rather than every single font style in the entire app to change, this task became a lot easier (and a lot less prone to accidental typos).
Translating the Style Guide Into Code
In terms of the implementation, we had to deviate from the traditional path of just writing down a list of font styles and opted for multiple structs/classes which benefitted our code base in terms of modularity. Using our systemized style guide, we were able to make use of protocols in order to have single components exchangeable so that we could replace colors, font attributes, and even size classes for the fonts’ point sizes on each individual app.
We implemented the core elements of the whole style guide approach by defining Rows and Columns and defining a Theme protocol which would later be implemented for a specific app in order to provide the essential attributes for text styles.
Next, we combined all the attributes provided in our protocol, using protocol extensions, into a dictionary usable by the Foundation library for creating our attributed strings. The implementation of the theme protocol became really simple: we only had to implement the required functions to get a fully functional theme for an app.
By using dependency injection, we provided each view controller with a Theme instance which could be used to set the attributes of a given text with
myLabel.attributedText = NSAttributedString(text, attributes: theme.attributes(forRow: .r4, column: .c1).
One More Thing…
This style guide comes in handy for working with Interface Builder in Xcode; all font attributes can be expressed as a set of two numbers which form a common language between both designers and engineers. By creating a few custom classes for labels, text fields, etc., it becomes possible to make the theme for a label in interface builder “inspectable.”
By using those stylized UI elements, both designers and engineers can customize UI elements and see the changes in visual appearance without having to touch any code at all.
Designers and engineers use different tools and approaches when working with typography. This can introduce many challenges to scaling text styles throughout implementation. By applying the style guide system outlined in this post, designers and engineers can work with each other, better communicating through a common and systemized language.
We hope you love this grid system as much as we do! Even though it’s still in its earliest stages, we believe it has a lot of potential and we’re excited to see how it can be improved and scaled for more design and engineering collaborative experiences.
Have questions or ideas? Send an email to firstname.lastname@example.org.