Design System Sketch files, Two years later

SimilarWeb design assets architecture, explained and revisited

Whenever I talk about Sketch before the age of Sketch libraries I feel like going into an explanation of a strange hack that everyone did with icons and layer fills:

Before you could use layer styles overrides in symbols (Version 51, July 10 2018), we used to create small symbols that are just coloured squares, and used icons and buttons as masks for these symbols. It’s less complicated than it sounds. That way you could easily override the color of an icon or a button symbol on Sketch.

Given that, using this method of masking the delivery on Zeplin and Invision was a nightmare to export and for the developer to inspect.

Not even mentioning the ridiculous amount of posts written about this hack.

It’s a good thing that Sketch app developers listened to the community and added Layer style override to the Sketch library update. Now we have all the tools to create a scaleable and flexible component bank for designers to use.

Back in 2017 I did a few design systems file architecture for different freelance projects, and I was asked to join SimilarWeb and create the design system files from scratch. After a few days of research we decided to use the atomic design mental module and adjusting it accordingly.

When thinking about the needs of the designers using these system, we had a few goals in mind:

1. The files would be easy and fun to use — It should save designers time and work like magic. Use emojis in symbols names for readability. Make the names as intuitive as possible. Use directories in layer names for organising the overrides menu. Lock layers that would not change so the override panel wont get messy.
2. Separate files whenever is possible — Not working with large endless library files. Using multiple library files makes things easier to find on the components panel and to load.
3. Files inherit from one single source — That feeling of “new library update” tag on the right, that is going to mess up your document — this had to be solved somehow. In the solution we eventually came up with this problem still couldn't be fixed (meaning inheriting changes from multiple libraries was still needed), even when using one-way inheritance.
4. Single designer-facing file — designers would work only with a single sticker sheet file — the libraries files architecture should be invisible for them. Designers should look for a component in a single file. Plus, there is only one file that get uploaded to Zeppelin / Invision.
5. Brace yourself for changes — Every time Sketch updates the mental model of the files and / or software (like they did with layer styles in libraries 2 years ago, auto-resized symbols and components panel) we shouldn’t have a single point of failure within the files. Everything should be easily adjusted to fit the new model.

All files are hosted in a dropbox folder that only I have writing access to. all designers could view it and learn from it.

So, how did we build this?

Base files (Atoms)

🔶 Primitives.sketch — This file contain all of the basic building blocks of the design — colors, icons and typography. This is the only file that would contain style overrides. Here is a partial list of what’s in the file:

• All text styles (for titles and components)
• All colors of our design system as document colors (and meaningful ones as layer styles)
• Charting colors (Used for graphs in the product) as fill style and as strokes styles
• Materials and surfaces as layer styles and as a symbol (cards elevation, tiles, hovers, etc)
• Websites favicons and mock data— when designing the platform we often use example websites in our mocks, so we have about 20–25 websites from different industries we like to use.
• Mouse cursors, Touch gesture circle indicator and OS assets such as scrollbars.

🔶 Icons.sketch file containing just icons that is automatically exported to svg assets when building the codebase.

Composites files (Molecules)

🔶 Composites.sketch file containing the basic product components:

• Buttons
• List items
• Form components (Text fields, toggles, radio buttons, checkboxes etc)
• Chips, labels, tags
• Scorecards (Number header formatting)
• Widget titles, pagination, Platform components

🔶 Navigation.sketch — containing all navigation assets of the platform. This was a separate file since it contained icons and styles that are only used in the platform toolbar (and not anywhere else). I felt it’s a good use of a standalone file, since it only inherits colors from the primitives file.

🔶 DataTables.sketch — In an effort of breaking down large files, this one contains all the table cell types, table headers and table footers we use on the platform. this file is relatively large and hard to use on its own without examples and guidance.

🔶 Charting.sketch — All charts and data visualisations in our platform. line charts assets and axis overrides, donuts, bars, stacked bars, XY plots, chart legends etc.

Designer-facing files (organism)

🔶 Stickersheet.sketch — a file with all components in all states (we call it “molecules”). This is the file all the designers usually work with. The components panel was a great addition to the UI, but it shows only the base component — but not all of the possible states of this component.

For example — we use the text box also as a dropdown base button and also as a password validate (when the icon on the right reveals the password).

All of the text boxes in this screenshot are composed of the same symbol

This one component has many uses that are only depends on the override, and isn’t reflected in the component panel. the stickersheet file allows you to show a more complete image of what you have.

I would say it’s ideal to have less components with the least overrides, but in case these two clash, the logic would be to create a component for a distinctive product need, like separating a password field and a text field, rather then allowing the designer to override multiple properties in order to get it into the right state. This saves time, enforces more accurate results and works better with Runner.

🔶 Layouts.sketch file with example pages using the components and styles. when doing a modification to an existing one we usually worked on a screenshot of the existing page and some white squares to cover the new area we needed to change and the file became messy real quick with multiple screenshots one on top of the other. This still happens — but having a Sketch file that is up-to-date with production gives you the tools to work in a more organised fashion.

🔶 Illustrations.sketch All illustration we had in the product, keeps updating as we create more — only inherits the colors from the Primitives file

Aftermath (after 18 months of daily usage)

This Implementation was done over a year and a half ago from the time i’m writing this (November 2019). Meanwhile, a new team member took over my position as the facilitator of the design system — Gilad Izrael.

I talked to him about the maintenance of the design system files in the past months and learned a few new things that I didn’t think of while drafting the original documents. He also did an amazing job maintaining it and finding ways to improve it —

• The first thing he did was a design survey about the usage and implementation of the current design system. Here are the 3 verticals he asked the designers about:

What are the design problems with the components? — Was there a better way of designing this component? Anything else came up that is more suited to the use case?

Are there any technical problem with any of the components? — Are they comfortable to work with? Are all the overrides necessary?

Are there any documentation problems? — Knowing what to look for, understanding the purpose of each component and when to use it, etc)

• There was a large gap between how pages looked in the design system and what was actually going on in the platform itself. designers were still working on top of screenshots. Currently there is still no solution to this issue, and there is a debate weather is this really a problem.
• The data tables symbols were the hardest component to work with. Each cell was done as an individual symbol and even with plenty of examples designers still took plenty of time building new tables.
• Onboarding new designers was a hassle — new designers took a while to understand how to work with the sticker sheet file and where to find components.
• There was no documentation for the usage of each component. We once talked about creating a guide similar to Google’s material design that explain when to use each component and the basic rules of the platform design. New designers were only learning from trial and review. Even placing a text paragraph inside the sticker sheet explaining the usage of each component would help.
• Designers like working with Runner plugin, that could only access library symbols and not sticker sheet instances. This made some components almost impossible to find on runner. This made him think about removing some of the overrides in favour of new symbols. This means more components with less overrides.
• It’s was better to work in a single library file than splitting up all of the files like I did. A few years ago 200MB+ Sketch files were slow and almost impossible to work with, But now it’s much easier. It would of been better to redo the library on a single file.
• Adding to that, the primitives file was no longer needed after the addition of layer styles override. It could easily be a part of the composite file.
  E.g When updating a color using 3 separate files — you first need to update the primitives file, then update the composite file, then the stickersheet. This just skips a step in this complexity.
• Always be aware of Sketch updates and changes. It’s part of your job now as maintenance of the sketch files.

In the end — I still haven’t stumbled upon a similar article explaining the entire file architecture of a design system in large organisation, and a follow up on using these files over time. I would love to see more Ideas and real use cases of these files, and learn from problems that other teams had.