Design system documentation

We might be overthinking this…

‍
…but, hear us out. We all agree Figma has taken over the production of UI/UX design, and therefore, most of the design community, as well as their fellow developers, project managers, project owners etc. depend on Figma. Kudos to Figma, but what about us?

At this point, all roles inside the design process are familiar with this tool, there are some exceptions of course, but as far as their job is concerned, they usually know enough about the interface, features, and prototyping. Dev mode is a whole another universe, and I won’t even try to go into that.

First design documentations were born in some of the previous versions of design tools, Sketch for instance, but, even before that, while we still designed websites inside Photoshop, and uploaded them to InVision, we actually wrote dev handoffs in Google Docs, and this was also a type of design documentation. As the tools evolved, together with the industry, our documentation became more and more complex.

Once we started working solely in Figma, our documentation followed features, and started becoming more tool based. This isn’t necessarily bad, but it is highly dependable. No one knows what the future will bring, but it is mostly probable that product owner won’t click through the Figma interface in order to find information, nor will our clients have the time. Typescale, sizing, spacing, color scheme, effect styles, grid styles, all these are indoctrinated into Figma as a tool. When it comes to setting up a design system, these features are indispensable. Of course, there is much manual labor involved, so to speak, but because of variables everything works smoothly, even changing color mode inside the user interface from dark to light, or any other color scheme, becomes easy. After many many clicks, you get to a point where in just 2-3 clicks you change an entire interface, or many screens, even the whole file, isn’t that worth those many many clicks before? In terms of business, absolutely, in terms of “we should’ve used that time to plant something”, definitely not. 😅

Focus on what we can control

Like I previously mentioned, tool based is cool, tool based is necessary, and tool based is out of our control. But, what we can control is the documentation. Yes, we do that also in Figma, but at this point it’s a practical matter, we like everything in one file, our clients also. What’s important is the visually presented documentation we create in whole, not just the result of it. If set up correctly, the design system works, even without the documentation, but by creating one, we ensure that nothing will be lost, and every information is readable to anyone.

Just bite the bullet

Of course it’s tedious, and takes up a lot of time, but after the main part is done, I feel like finally everything is in order, I can literally see my thoughts, and process of creating a design system, I don’t just trust the tool, I’ve created it myself, for different purposes, and now everyone can benefit from it, not just the design team.

If we take, for example, the general structure file for any product, in the first place we have a Styles page, which incorporates: icons, documentation for typescale, colors, color roles, spacing, corner radius, sizing, effect styles, grid styles, and if we agree, tokens documentation for all of these. The next page is the Components page, and if it is not necessary otherwise, here you can find all created components, and their documentation.

Typescale documentation is mirrored from the local text styles in Figma. So, that’s a no brainer. On the other hand, colors are much more complex. First we create a palette of shades for each selected color, from greyscale to primary, secondary, etc. We also add system colors, such as warning, error, info, and success. At the end, we show the color effect: we choose these to be color gradients, if those are a part of the brand guidelines, or user interface. These also come in handy, because Figma actually doesn’t support gradients inside variables. Well, not yet, at least. This means that, if you want to change a color mode fast, like I previously stated, from light to dark mode, the gradients need to be done manually. (Please, don’t give up on gradients because of this, it’s not their fault)

‍

Now, color roles. This is the moment your color shades become user experienceable (that is a word :D). We have, for example, accent, text strong, text hover, background, container hover, outline, link, etc. and all the roles should be mirrored in all your color modes, that is why we love shades, they do that.

Spacing, sizing, and radius are straightforward. We can do those with our eyes shut. We use even numbers, of course, divisible by 4 or 8. These are also applicable in the variables. Be it so, we like to give more context to sizing, so we add usage explanations.

‍
Of course, this is the base of every design system. The second part of the documentation process comes after we design and/or finish the components, and apply those previously stated variables. I will show this in only one component example. One of the most common is of course the list component, it is versatile, literally every user interface has some version of it, and the users are accustomed to it. This list component example comes from txSync products (Portal&Bridge), and it was part of a redesign venture we did last year.

The list component has four states that are clearly shown inside variants (default, hover, pressed, and disabled). On the highest level it is composed out of a container and content inside that container. On a more detailed level we can see the token icon, main headline, following text, main amount text, and following amount text. Our idea here is to show how something works, and the expected behaviour of the component in question. This means we show spacing, and sizing, whether container width and height are fixed, the value of the corner radius, alignment, text container height. We do this for every component. Elements vary, but the principle remains the same.

As you can imagine, this detailing takes a lot of time. When a design system gets to a point where the next step is component documentation we think twice if we did everything correctly, and will this have value in the long run. Of course, a lot of our web projects don’t have this level of design system, but our products do.

The many roles of design system documentation

Once I called myself an archivist of the design system, similarly to a librarian, but at the same time curator, or information administrator. However you call it, I felt like there is nothing visually to show, but it exists, because the system works, and that’s the proof. This non-visuality is exactly what is shown via documentation.