Hands-on Design System Documentation — Part 1: Basics
Learn by Making with Toolabs DSM
“A simple style guide is like a diagram of all the elements that make up a piece of IKEA furniture without the instructions telling you how to assemble them.”
Toolabs DSM provides an easy to use built-in editor to document your design systems.
First of all, our editor is similar to other rich-text editors with easy text formatting features.
In addition to plain text, it lets you embed media content from several sources, such as Unsplash images, Youtube or Vimeo videos and, Lottie animations.
What makes our editor special is the design system widgets that you can embed into your documents as easily as using other media objects. These widgets are connected to your design system repository and therefore they are in full-sync with your design tokens and components. With this feature, your documents are always up to date with your design system.
When you create a new design system, a default document is automatically created with predefined pages for each token type. You can either customize these pages if you like or delete them and start from scratch.
We are planning to make it possible to build multiple documents for the same design system library. Therefore it will be possible to publish one document focused on the needs of designers, one for developers or others for different parties with different focus areas on the same design system.
Arrange Pages and Folders
You can add, rename, delete pages and folders from the left panel.
You can also drag pages and folders to organize your document navigation items.
➥When the mouse is over an item, a drag handle is visible on the left to drag the item to arrange its position, and the dot menu on the right shows the list of the actions possible.
➥To use your logo, either drag & drop the image file to the drop area or use the toolbar to provide the Url of it. You can also set the alignment options of the image or remove the logo from the toolbar.
➥If you want to hide a page in published documents, then click the visibility icon on the navigation item.
➥You can copy the document page’s internal link from the navigation item in the left sidebar and use the link for navigating from text content or link card widgets in document pages.
Customizing Appearance of Document
You can customize the appearance of your design system document from the Style Editor.
➥Clicking the Style Editor button on the top right of your document will open the editor panel
You can also use tokens from your design system for styling. Customizable document sections are :
➥Background color, text color, and font styles of Left Sidebar
➥Background and deault text color of pages
➥Text styles of page contents
➥You can change the page content width and page top margin by clicking & dragging in the top section of the page.
Writing Text Content
Document pages are stack of building-blocks. The types of blocks range from simple texts, images to design token widgets or components pulled from your design system.
You can insert new blocks, delete or change the order of blocks on the page by using the toolbar on the left of each block. The toolbar is shown when the block is selected.
When you insert a new block, the widget wizard is shown. After clicking on a widget type, the block is activated with that widget type and the customization toolbar for that type is shown at the top of the block.
Every new page is automatically created with a text block. When inserting new text blocks, you can click on the desired text type from the widget wizard.
➥Within a text block, you can use different text types for each line. Use the text toolbar above the block to customize the style of the selected text.
Document Widgets
Image
You can insert images to your documents in three ways :
- Search from Unsplash galleries
- Embed with URL , or
- Upload from your computer
Then you can change the alignment and width of the image from the top toolbar, and provide a subtitle below the image.
Video
You can add videos to your documents from various streaming services including YouTube, Facebook, Twitch, SoundCloud, Streamable, Vimeo, Wistia, Mixcloud, and DailyMotion.
After inserting the video widget, copy and paste the URL of the video to the top toolbar.
You can also change the alignment, width, and height of the widget from the toolbar.
Lottie Animations
It is very easy to use Lottie animations in your documents.
Lottie is a high-quality After Effects animations played on the web. You can browse Lottiefiels for beautiful and high-quality animations and then copy the animation URL to your widget.
You can then change the alignment, width, and height of the widget and playback speed of the animation from the toolbar.
Link Blocks
You can use Link blocks for displaying and previewing external or internal links.
After inserting the widget, paste the URL of the link to be redirected.
You can display an image in the card along with a title and short description, all of which can be styled from the toolbar.
Tabs and Accordions
This widget lets you group content in list of tabs or accordion. Each list item can be composed of multiple building blocks, similar to pages.
You can change the view type between tab amd accordion from the editor on right panel. You can also add, remove, rename, or change the order of items from this panel.
Two-Columned Layout Blocks
With this widget, you can display content side-by-side in two columns. For each column, you can insert any widget available in the wizard.
To remove content from a column, move the mouse over the column and then click on the Delete icon which is on the top corners of the column.
Spacer Between Blocks
You can use the spacer widget to insert vertical spacing between two blocks.
It is also possible to give the bottom margin to each widget which is placed below the widget itself and is activated when the mouse is over the bottom margin area.
Divider Between Blocks
You can use the divider widget to insert horizontal lines between blocks.
Divider color can be set globally from the document Style Editor.
Embed Online Content
You can embed any online content in your documents if the URL of the content is allowed to be viewed in iframes outside of the original domain.
After inserting the iFrame widget, copy and paste the URL of the content to the top toolbar.
You can also change the alignment, width, and height of the widget from the toolbar.
➥The Example below shows embedding an interactive online coding environment from Codesandbox.
Figma Live Embed
You can embed real-time Figma designs and prototypes in your documents.
After inserting the widget, click the Share button inside a Figma file and copy the link to the file. Then paste the copied URL to the top toolbar of widget.
If you want to embed only a single frame from the Figma file, then check the “Link to selected frame” option on the share dialog.
You can also change the alignment, width, and height of the widget from the toolbar.
Page Hero Section
You can easily add hero sections to document pages, with/without background images and hero messages.
- Click Add Hero button on the top left of the page
- Add background image: either select from Unsplash, upload or give the URL of the image.
➥ To adjust the height of the hero section, just point the mouse over the hero section, then drag it up and down.
Then, by clicking on the plus button on the center of the hero, you can add any widget into the hero section just like adding content to pages.
Preview and Share Documents
➥ When the real-time team collaboration feature is released, there will be advanced options for publishing releases and sharing your design system documents.
For now, those who have a shared link can preview that document.
You can instantly preview your documents when designing and see how it will be when shared. Preview and Share buttons are on the top bar next to the navigation dropdown.
For example, if you are building a multi-brand design system and want to share your document with design tokens customized only for a specific brand, then create a custom link and configure the theme for that brand.
For example, if you are building a multi-brand design system and want to share your document with design tokens customized only for a specific brand, then create a custom link and configure the theme for that brand.
Part 2: Document with Design System Widgets
To learn more about Toolabs DSM for Creating Themes, Exporting Tokens, Querying Tokens with GraphQL API and Plugins for Figma and AdobeXD, visit the learn center:
