1 of 26

Applying a Design System to Your Document Design

Leah Catania

Content Strategist, Technical Communications

TraceLink, Inc.

PRESENTED BY

2 of 26

Introduction

Design and develop document design
Work closely with UX to develop IA and user flow patterns
Led the project to write TraceLink’s Anthem Design Guide

Content Strategist at TraceLink, Inc.
7+ years of technical writing experience
8+ years studying and performing usability testing
7+ years of industry experience in pharmaceutical supply chain (heavily regulated)

3 of 26

Agenda

Design System Guides

What are they?
Examples
How to use the guides

Developing document design

Typography and colors
Backgrounds
Skins
Replicating a header with a side nav skin
Buttons
Iconography
Components

Today, I’ll be going over the basics of design system guides: what they are, some examples, how to read the guides, and what’s most relevant for you as you’re working on your document design. Then I’m going to show you some specific examples of developing typography and colors, backgrounds, skins, replicating a header when you’re using a side navigation skin, buttons, and iconography, all based on the design system.

Summary:

As writers, we aren’t always as skilled visually as we might want to be when it comes to creating a document design. Some of us are lucky enough to work with user experience designers or developers who can create our designs for us, but what do you do if your team doesn’t have that option? If your UX team has an established design system, you can leverage it to easily build your document design in a way that matches the company’s branding and product UX. Learn how to read a design system guide or UX style guide, how you can use it to design your documents, and how to translate those designs to CSS and skins in Flare so that your final output fits in seamlessly with your company’s overall design system.

4 of 26

Design system guides

5 of 26

What is a design system guide or UX style guide?

Set of standards, with reusable components and patterns, to design at scale easily, with consistency
Desing system guides define:

Styles
Components
Patterns
Downloadable resources (often)

Easily learn and adapt to the system, so all experiences are consistent in brand, style, visuals, and voice

A design system itself is a set of standards with reusable components and patterns, to design at scale easily with consistency.
The guides for those systems, at a minimum, usually have sections that document the styles used across the system, the components that comprise the system, and the patterns those components can be used within.

They also often include a set of downloadable resources that can make it easy for designers to take the styles, components, and patterns and move them into their own design software to create mockups. While we don’t usually have design software available as writers, more and more often, these design files are available through web browsers with just a basic login, and we can often pull out a lot of valuable information from them to make our job easier.

The purpose of the guides is so that designers (both internally and externally, depending on whether the guide is publicly available), can easily learn and adapt to the company’s design system, and create experiences that are consistent in brand, style, visuals, and voice.

6 of 26

Examples

Design system guides

7 of 26

Atlassian Design System

8 of 26

SAP Fiori for Web Design Guidelines

9 of 26

Google Material Design

10 of 26

TraceLink Anthem Design Guide

11 of 26

How to use design system guides

Design system guides

12 of 26

How to use design system guides

High-level information about how to use each piece of the design system

“How to” for designing experiences within that brand

Detailed information about specific best practices
Use the colors, typography, and iconography provided to inform design decisions
Use the downloadable resources for CSS and other style information

The guides themselves provide high-level overview information about how to use each piece of the design system.

Think about it as a “how to” for design experiences within that brand.

You’ll also find detailed information about specific best practices, do’s and don’ts, and implementation guidelines.
You can take the colors, typography, and iconography directly from the guide and use them for your color choices, font styles, and icons in your document design.
Finally, make sure you leverage the downloadable resources as much as you can to copy CSS or replicate other style information, especially for individual components.

Even if your company doesn’t have an explicit design guide, or doesn’t provide downloadable resources publicly, you can likely get these files from your UX or marketing team. They should be able to provide them to you very easily, without much, if any, work on their side.

Let’s look at an example

Get started sections can often provide you with a roadmap for where to focus on in the guide based on what you need.
Most guides have some kind of “Foundations” section or “Style” section. This usually contains the most useful information for doc design. It gives you information on the building blocks that the entire design system is made of. Understanding these foundational styles makes it much easier to understand the components and patterns that use them.

You can see here that the Colors topic gives information about the primary and secondary colors, including when to use them and how to use text with them. They also often contain semantic colors, which are colors that have specific meaning to them that always need to be used consistently (make sure to show the semantic colors section). Adhering to these guidelines can be the most important part of making sure your docs are aligned with your company’s brand vision.
Same goes for the typography. You should take the styles provided here and incorporate them into all of your heading and span styles so your text is consistent.
The iconography topic here provides some useful Do and Don’t example, which are very common in public-facing design system guides, and give great information about how to interpret the guidelines given.

The components can be helpful for things like buttons, links, and navigation.

Sometimes the guides contain information for actually developing inside the company’s UI building tools. If you’re not leveraging those tools, you don’t always need that information, but there can be helpful code included that you might end up leveraging if you’re trying to incorporate certain features into your Flare project that mimic the components provided by the system.
The usage section of the components is what you’re most interested in here, where it will walk you through the proper places to use the component, its best practices, and what you shouldn’t do with it.

When it comes to the design system’s content guidelines, if they have them, hopefully the writers have been involved in creating them, or are at least already familiar with using them for writing UI text.

Sometimes they contain information for more longer-form content, depending on the purpose of the design system, but more often than not, this will be superseded by your own writing style guide.
However, if you’re a very small team and you don’t have a formal writing style guide, this can be a great starting point, in addition to a standard guide like the Microsoft Style Guide.

Patterns can be really helpful for building your page layouts and figuring out how to structure your IA.

Atlassian doesn’t have a lot of whole-screen patterns, but if we switch over to SAP for a minute, you can see here that it provides you with screen layouts for specific use cases, outlines which components get used where and how those components should be configured, which you can base your master pages on, especially if the design system is built around long form content or provided by Marketing.

Finally, the design files can provide you with actual CSS that you can take and insert into your Flare CSS file.

<Open the Atlassian Components Figma file>
Primarily, they’re for designers to be able to build mockups with the components provided by the system, but most design tools have a developer mode that you can turn on, which will let you pull the CSS for the designs right from there. You might have to adjust it once you get it into your CSS, but the most important things are already there for you.
If your company doesn’t have publicly available design files, and you’re not closely integrated with your UX or Marketing teams, you can ask them for their design system files or their “sticker sheet” (which is what UX designers often call files like this). You could also go to a design guide like Atlassian’s and show them the Figma files, like this sticker sheet here, and ask them if they have something like that, with dev tools that you can enable to inspect their designs for the styling. I actually just did that a few weeks ago. Our UX team is in the process of migrating our design system files from Adobe XD to Figma, and I couldn’t find any of the iconography in the sticker sheet UX had sent me, so I sent our Design System Lead the link to Atlassian’s iconography section of their style Figma file, and asked if we had something like that. He said it wasn’t quite done yet, but here’s the link to what he had, and that’s what you’ll see a screenshot of later on in this slidedeck.

13 of 26

Developing document design

14 of 26

Typography and colors

Anthem Design Guide

CSS

So here, I’ve taken the Heading 1 style from the guide, and set them into the h1 class in my CSS.

You can see that the values provided by UX are in pixels, which is common, because mockups are usually handled in pixels. However, pixels aren’t responsive in web design, so I converted those to rem for the size, and the line height doesn’t always play nice in Flare, I’ve found, which is why I’ve added a padding at the top instead.
I’ve also added a backup font, which was specified elsewhere in the typography topic.

The color I’ve specified for the H1 is a variable, and on the right, you can see that I’ve entered all of the brand colors, as well as UX’s standard shades of gray, black, and white, so that I can easily call them in all of my classes.

This is probably the most straight forward use of the design system guide, and most of you are probably already used to this if you have any kind of design mandates from Marketing or UX.

15 of 26

Backgrounds

Use div.off-canvas-wrapper to keep background images from displaying in the XML editor

background: var(--secondary-background-color-gradient-background, linear-gradient(270deg, #003D4C 0%, #006343 100%));

CSS

Anthem Design Guide

Figma

As you’ve might have noticed from all the screenshots, TraceLink’s design uses a gradient fairly heavily. Luckily, it’s a very simple gradient, so it was easy to turn it into CSS based solely on the information in the design guide. The Figma design files also specify the gradient – that’s where the orange box is from – but it’s a little more complicated than it really needs to be, which is why I have the simpler version in our CSS.

As an extra tip for you: If you ever need to put in a background color, we usually use the .main-section class, but the class you see here – div.off-canvas-wrapper-inner – is where you can set a background color without having it appear in the XML editor, which lets you use a dark background color like this without impacting writers as they’re working.

16 of 26

Skins

background: linear-gradient(180deg, rgba(37, 37, 37, 0.20) 0.33%, rgba(255, 255, 255, 0.20) 100%);

If you need a background with partial transparency, use an image

Figma

This is a screenshot of the Figma file for our side navigation in the product. The Layout and Style box is where you’ll get most of your information from in Figma. For some reason, this one uses RGB values instead of hex codes, but from that, you can tell there’s transparency being used here—the 0.20 a or alpha value that indicates how opaque the element should be – in this case, only 20% opaque, which is fairly transparent—which is unfortunately a red flag for Flare. The CSS can’t handle a transparent background. When you put a transparency on the background, it applies it to the entire element.

So, how do we fix this? If there’s something that needs a transparent background, you’ll need to get an image from UX or Marketing to use as the background, instead of doing it solely through the CSS. Knowing this early is obviously helpful, because the sooner you know you need something from another team, the more likely it is that you’ll be able to get it.

17 of 26

Skins

CSS

Skin Editor

On the right, you can see that I have the background-image set, which is what will give me the gray transparent overlay on top of the gradient, which gives the “glassmorphic” effect UX is going for with this design.

I’ve also put in some extra CSS so that the chevron Open and Close icons move in the same way that our product does, because Flare’s Open and Close icons don’t match how our product is built. This took a lot of extra work to figure out, and wasn’t something I could just pull from the design files, but it really makes a difference in ensuring that the documentation, marketing website, and product are all aligned.

On the left, you can see how I’ve set the menu item styling, following information I found in the Layout and Style section of the design files for each piece of the navigation.

I do just want to take a moment to point out that if you’re trying to do anything more than basic edits to the skin, especially if you have very specific styling you need to mimic in the side navigation, it can be extremely helpful to just use the CSS, rather than the skin editor in Flare. The skin editor is fabulous if you don’t know CSS very well, or if you just need to make basic changes, but by using the Inspect Element of your browser, you can find basically every class you might need to style, including things that just aren’t available in the Skin editor, like flipping those Open and Close icons. At this point, because we have such a custom side navigation, I use the CSS for pretty much everything except defining the styling for the menu items.

18 of 26

Replicating a header with a side nav skin

Master Page

Output

One thing that you often see in websites that Flare isn’t really set up for is a header in addition to a robust side navigation. The old-school tri-pane skin can kind of do this, but styling it to look modern and match something your product or marketing team has built is pretty difficult.

Instead, what I’ve done is leveraged the master pages to build what looks like a header, although there isn’t any navigation in it (which means it doesn’t require integration with a TOC).

I made a responsive layout for this ribbon div, so that the document title could respond nicely with the search bar, while keeping the search bar on the right side of the screen, in line with the product. The styling for the ribbon background came straight out of our design files for the header in the product. We were also playing around with making it a sticky header, so that when you scroll, it stays at the top, but we didn’t have enough time to devote to that effort to get it working perfectly, so it’s currently commented out.

In the future, this also gives us a perfect place to put a version selector, so that users can switch between different available versions of the documentation, something that gets requested fairly frequently.

19 of 26

Buttons

CSS

Output

Figma

20 of 26

Iconography

21 of 26

Building a card component

Demo

We’re going to switch gear now and look at a live example of some of the things we’ve been talking about.

We’re going to go through the Figma sticker sheet for this Summary Card component, and add in the CSS to style the cards the same way.

This is what we’ll be trying to build. The product uses this component to represent objects in the system, and Marketing and Documentation use this on section landing pages to link to the child pages in that section.

I’ve created a responsive layout for the cards, and determined which classes I need to build each part. This is what it looks like with zero styling applied. Now let’s get the CSS set up for each class. Like with the skins, I prefer to work in the text file of the CSS, rather than Flare’s CSS editor.

<CTRL+F for landing-cards to find the right styles>

<Go through:

Card styling
Title, p, and a styling
Card button container & button>

22 of 26

Final result

23 of 26

Final Result

24 of 26

25 of 26

26 of 26

Questions?

Extra Information