Tips on organizing your design files for zeroheight
Jules Mahe
Building a design system isn’t just about having a UI library. While documentation is the cornerstone of a design system, it can appear burdensome because it takes time and effort to write and it feels like nobody will read it.
However, by providing visual examples, you can make your design system documentation much easier to read and more appealing. That’s why we provide visually engaging features such as shortcut tiles, rules, embed content, tables, and much more.
But the more visual your documentation is, the more organized you need to be with your design files. You may be wondering how, and we’re glad you asked.
We have advice and tips on setting up your design files and styleguide to help you create engaging documentation. We even have a Figma file template you can use to get started!
Design files architecture
To prevent your design system file from becoming too complex and running into performance issues, it is best to have a separate file dedicated to the visuals in your zeroheight styleguide. Visuals would include any images you’d show for do & dont’s, examples, shortcut tile thumbnails, covers, etc.
Even though it’s a separate file, we recommend it uses components from the design system UI library. This way, your visuals and examples are always up to date. Suppose you’re adjusting the radius on some form components in your UI library. Because you imported those components into your documentation file, you won’t have to edit and change all the visuals. Even the rules blocks and your design examples will sync on zeroheight since you have your files synced.
Design files architecture: link your documentation design file to your UI library and sync both with zeroheight
Organizing your ‘documentation’ design file
Design systems bring consistency to projects; likewise, organizing your files should be consistent.
Your documentation design file should follow the same logical structure as your zeroheight styleguide. It should have three types of pages to meet all the visuals you need in your documentation:
- Homepage: this is the first page of your styleguide.
Your design file should contain visuals for your cover and the thumbnails for the shortcut tiles. You only need one page of this in your design file. - Category-level page: this page is for categories you enabled as pages on zeroheight.
Your design file should contain visuals for hero image and shortcut tiles thumbnails too. Duplicate the categories-level page and create as many as you need. - Page: this is for each page you created on zeroheight for your different patterns (colors, header, shadows, card…).
Your design file should contain visuals for hero image, rules blocks (do & don’ts) and some examples if necessary. Duplicate as many of these pages as you need.
As each type of page has its own set of visuals, organize your design file to be ready to export or sync to zeroheight. To do this, keep your documentation organized and maintainable by using the following rules and guidelines.
You’ll notice that categories-level pages are uppercase in the Figma file template. It’s just one way to keep consistency with zeroheight as categories are uppercase in the sidebar even though it’s something you can change now in zeroheight.
Homepage
What’s inside?
The zeroheight styleguide homepage has two types of visuals: the cover page and the shortcut tile thumbnails.
- The cover image is likely the largest one in your styleguide. For this reason, it is best to select captivating and immersive visuals. Get some inspiration on our showcase to see how other design systems such as Brainly, MangoPay or Helly Hansen play with this cover image using GIF animations and immersive visuals.
- Below the cover image, you have the possibility to add some shortcuts which provide convenient access to the main sections of your styleguide.
You can also use the homepage if you need a place for your styleguide’s logo. Although the logo is not specific to the homepage (since it runs across the entire styleguide), it is the starting point for building your styleguide so the homepage section of your file is a good place for it.
Visual sizes
Cover page
Due to the responsive nature of the styleguide, the cover image will fit the available space. As a result, the image may crop differently depending on the screen size. This can make it difficult to identify the optimal dimensions. The best choice is one that will display nicely on multiple screen sizes.
If you want the image to seem crisp on most displays, we strongly recommend a width of at least 1920px. The height, however, is determined by the height of the cover page; if the cover page is full height, a height of 1080px would be appropriate.
Shortcut tiles thumbnails
By default, the ratio for the shortcut tiles thumbnails is 2:1.
We suggest creating an artboard of 400x200px and defining a 2x export option to get consistent and high quality visuals for your shortcut tiles. If you need larger visuals, just start with these measurements and constrain proportions when you enlarge your artboard and you’ll maintain the ratio.
If you have the Professional or Enterprise plans, you have more ratio options. Here are the different shortcut tile sizes:
| SMALL | MEDIUM | LARGE |
| 4 column = 2:1 (400×200) | 4 column = 1:1 (400×400) | 4 column = 4:5 (400×500) |
| 3 column = 3:1 (600×200) | 3 column = 3:2 (450×300) | 3 column = 1:1 (400×400) |
| 2 column = 4:1 (800×200) | 2 column = 2:1 (600×300) | 2 column = 8:5 (640×400) |
| 1 column = 8:1 (1600×200) | 1 column = 4:1 (1200×300) | 1 column = 4:1 (1600×400) |
In the Figma file template, you can find the shortcut tiles artboards in the ‘shortcut tiles thumbnails sizes’ page. Just copy the ones you need and paste them into your respective pages.
Naming convention
This homepage section will only have exported images that you’ll upload to your styleguide. So it is important to optimize how it will be saved on your computer. We’ll use the / convention to organize your exports into proper folders to achieve this.
Cover image
If you have a logo and the cover image in this page, add a Homepage/ prefix so your visuals will appear in the ‘Homepage’ folder. It should looks like this:
- Homepage/Logo
- Homepage/Cover-image
Shortcut tile thumbnails
If you’re using shortcut tiles on the homepage, create a ‘Shortcuts’ folder and specify a ‘Homepage’subfolder. This is to anticipate other subfolders you’ll probably have for your shortcuts later. It should look like this: Shortcuts/Homepage/Shortcut-name.
Replace ‘Shortcut-name’with where you want the shortcut to go.
For example, if you want to display shortcuts to your components section, your brand section, your contact channel, and your about us section, it would be something like this:
- Shortcuts/Homepage/Components
- Shortcuts/Homepage/Brand
- Shortcuts/Homepage/Contact
- Shortcuts/Homepage/About
Categories
What’s inside?
You can turn categories into category-level pages if you need to have a level before your pages. It can be useful if you have a large category with plenty of pages and you need to have an overview of the category. In the end, what is inside a category-level page is very similar to the homepage – you can display a hero image and then some shortcut tiles to point to related pages in this category.
Decathlon using category-level page to display pages
Visual sizes
These visuals are very similar to the homepage. You can enable a hero image (similar to the cover image) at the top and display any rich content below (usually, using shortcut tiles to point to the different pages inside this category), so sizing for these visuals is the same as for the homepage.
Naming convention
Similar to the homepage, the category-level page will only have exported images youâ’ll upload to your styleguide. So once again, it’s all about optimizing your folders when exporting.
Hero image
If you’re using a hero image, create a ‘Hero’ folder to organize the different hero images you’ll use across your styleguide. Add a ‘Category’ folder right after and finally, the name of your category. This is what the structure would look like: Hero/Categories/Category-name.
For example, if you have multiple hero images for your categories, it would be something like this:
- Hero/Categories/Actions
- Hero/Categories/Content
- Hero/Categories/Forms
- Hero/Categories/Navigation
Shortcut tiles thumbnails
The same goes for your shortcut tiles. We’ll just replace the first subfolder to create a ‘Categories’ subfolder and add the related ‘category-name’ so we can have something organized. This is what it would look like: Shortcuts/Categories/Category-name/Shortcut-name.
For example, let’s say you have a Forms category-level page, with shortcuts pointing to different forms components: checkbox, radio, inputs, dropdown, toggle, etc. It would be something like this:
- Shortcuts/Categories/Forms/Checkbox
- Shortcuts/Categories/Forms/Radio
- Shortcuts/Categories/Forms/Inputs
- Shortcuts/Categories/Forms/Dropdown
- Shortcuts/Categories/Forms/Toggle
Pages
What’s inside?
Pages will represent your components and patterns documentation: buttons, forms, navigation but also colors, fonts, shadows, etc. This is where visuals are very important to make your documentation appealing and useful. There are three main types of visuals to make this page engaging for your users: hero image, rules and examples.
- The hero image is similar to the homepage and category-level page: it’s a large visual you can enable at the top of the page.
- Rules are your dos and don’ts to explain how to use (or not use) your components and patterns.
You can sync your rules visuals directly with zeroheight, so there’s no need to export those. - Examples are visual representations of your component or pattern you’d need to display in situ to provide helpful context.
For instance, it might be relevant to have an example to explain how a tooltip popover behaves or where a floating action button should be positioned on a page.
Page artboards in design file
Visual sizes
Hero image
Hero images can use the same guidelines for the category-level pages and homepage.
Rules
Although there is no image ratio for rules blocks as the height will adapt to your image, there are still a few tips to consider to optimize your workflow.
- First of all, visuals for rules can be synced with zeroheight directly, you don’t need to export those visuals (but you can if you want to). That’s why we strongly recommend using components and patterns from your UI library directly in those visuals to ensure your rules examples are always up to date with your last UI library updates.
- Even if there isn’t an image ratio to follow, as you’ll probably use some real components to illustrate your rules, we recommend having a decent size artboard. We suggest starting with 940 x 460px as it gives you enough space for most of the components (cards, lists, pop-up, etc). Starting with this default size is a good balance for most of your components.
- Feel free to adjust it for smaller components (checkbox, toggle, icons, etc) or very large components (header, footer, snackbar, etc). You may also need to adjust the height if you have mobile components you need to display with a mobile device visual.
Although our rule blocks work with any images, we understand that you might need to adapt the background color for dos and don’ts to fit your brand or your visuals. That’s why if you’re on a Professional or Enterprise plan, you can customize the background color for your rules blocks.
Examples
Although you could just display some screenshots in your styleguide, we think it’s more ideal to build your examples in your documentation design file directly.
As for the recommendations, you can sync your examples with your UI library to keep your visuals up to date. Then if you just need to edit your examples, it’s smoother to sync your documentation design file to zeroheight rather than exporting and uploading a new image on zeroheight at each edit.
Regarding the size, starting with 1080 x 640px seems to cover most of the cases. This width lets you build some real page examples (a header usually fits in this width) and the height is just what you need to ensure your example can be visible on any screen without scrolling. Of course, it’s only a suggestion and you will probably need to adjust it depending on your specific use case. A mobile example may require a higher height for example.
If you need to have more advanced examples with prototypes for example, we recommend starting with an 848x360px artboard as it is the default size that will render your embedded prototype on zeroheight. Of course, you can adjust the size of this artboard if you have larger prototypes to render. Otherwise, just use this standard size if you don’t want to adjust your prototype on zeroheight. Remember you need to use our embed feature if you want to display prototypes.
Naming convention
Hero image
The hero image is the only visual you need to export on this page. So, you only need to optimize the naming convention for your folder organization.
We start with a ‘Hero’ folder to organize the hero images needed across your styleguide. Then, add a ‘Pages” folder right after and finally, the name of your page. This is what the structure would look like: Hero/Pages/Page-name.
For example, if you have multiple hero images for your different pages, it would be something like this:
- Hero/Pages/Header
- Hero/Pages/Primary
- Hero/Pages/Cards
- Hero/Pages/Icons
Rules
As you don’t need to export the visuals for your rules, we’ll focus on optimizing the naming conventions to simplify your search experience in the zeroheight design upload modal. We won’t use the / naming convention to optimize how it renders in the search results. (You can do this, but the more you add a / in the names of your layers, the more folders it creates, so the more difficult it is to quickly find what you’re looking for in the search results.) Instead, we’ll use one hyphen ‘-‘ to make it easier to read. The structure should be the following:
- Do Page Name – Description
- Dont Page Name – Description
- Caution Page Name – Description
Writing the ‘do’, ‘don’t’ or ‘caution’ with the name of the page will make it easier to search. With only 3-4 letters, you can quickly find the rule you’re looking for.
For instance, by starting to type ‘Don’ you’ll filter all the ‘Don’t’ rule images you have in your file.
Examples
Similar to the rules, you don’t need to export example visuals, so we’ll just use a naming convention to improve your zeroheight search experience. Importing a design file will display the name of your artboards below it by default. We suggest using this artboard naming as your example details. Write the description of your example as the name of your artboard so it’s easy to find once you’ve imported your example.
Wrap-up
You should work on making your documentation impactful to make your design system appealing and easy to read. To achieve this, here are the main key takeaways from this article:
- Use a separate file to keep your work organized
- Link your documentation design file to your UI library to ensure your documentation is always up to date, easy to maintain and syncs smoothly with your styleguide
- Be consistent with your visual sizing
- Optimize your exports and synchronization with zeroheight by using the right naming convention
- Use our Figma file template to start your documentation design file
Organizing your documentation will benefit your design system by saving you time, engaging your team to collaborate in a more organized way and bringing more consistency to your documentation.
Let us know how you’ve organized your documentation design file
Now that you know everything about organizing your design files for zeroheight, don’t forget to download a copy of our Figma file template to help you get started!
We’d love to hear from you if you try this or have used other ways to organize your documentation for zeroheight. Let us know what’s been helpful for you and feel free to share screenshots and files with us. We love geeking out about documentation and file organization!