Should I Upgrade to the New DSM?
This article references the new DSM, released for Early Access on May 5, 2020. Built on feedback from DSM customers, the new DSM offers a completely redesigned experience. Learn more about why we made the new DSM.
Built on feedback from DSM customers, the new DSM offers a completely redesigned experience. The new DSM is currently available in Early Access with more features being added soon.
If you’re still using legacy DSM, this article will help you decide whether to upgrade now or wait until a more robust automation workflow is available.
If you decide to upgrade, you won’t lose access to legacy DSM. Your original libraries will continue to function as they did previously. When you import a legacy library into a new design system, you are copying data—not overwriting existing data.
Reasons to wait
In June 2020, import flow tooling will be in place to help you import existing legacy DSM libraries into new DSM design systems.
If you decide to wait, the import tooling will:
- Automatically copy your legacy folder structure into your new DSM design system (folders; sub-folders; and component hierarchy, names, and descriptions)
- Automatically copy your rich text, images, and external links
- Automatically connect symbols to web documentation that was imported from legacy DSM. It does this by connecting with uploaded Sketch libraries.
- Automatically copies your Storybook entries
We recommend exploring the new DSM now. However, you may want to wait until June to import your libraries if any of the following are true:
- You have multiple legacy DSM libraries that your organization actively uses.
- Your legacy DSM libraries contain a significant amount of rich text and documentation that would be tedious to copy and paste into a new DSM design system.
- You have embedded multiple coded components via the Storybook integration or third-party external links.
- Your team actively uses DSM tokens for colors, text styles, and icons.
- You are content with the overall folder structure/hierarchy of your DSM documentation and would like to see it imported over as is.
Preparing to upgrade
Before upgrading—either now or when the import tooling is available—you’ll want to take these steps, ensuring the smoothest migration possible:
- Use a Sketch master file alongside your DSM library, and keep it updated (i.e., use the Sync to document button if changes are made outside of the master file).
- Convert all layer groups into symbols. Sketch libraries and the new DSM will only work with symbols, text styles, and layer styles.
- Create layer styles that use the colors you want in your DSM library, and upload them to the legacy DSM library. This is necessary because, in the new DSM, colors are pulled from layer styles only.
- In the legacy DSM plugin, organize Sketch symbols into component containers. To ensure compatibility with live components, place related symbols (like states and variants) in a single component container. If a symbol isn't in a component container, it won't be imported to DSM.
Manually upgrading during Early Access
If you’re eager to upgrade your legacy libraries now, and you’ve made the recommended preparations, you can take the following steps:
- Create a new DSM design system.
- Upload one or more Sketch documents via the new DSM plugin. As part of this process, consider following our best practices for using Sketch with DSM.
- Create your documentation structure on the web, taking consideration of how you want your design system to be presented and consumed by cross-functional users.
- Embed design assets into your documentation sites. These assets can come from uploaded Sketch documents, Storybook projects, and other third-party component libraries.
- Copy and paste rich text, documentation, images, and external links from your legacy DSM library into your new DSM design system.
- Add the new DSM design system component IDs to duplicated Storybook entries and republish. (You can keep the IDs from the original entries.)
- Invite teammates to your new design system and configure each person’s permissions.
- Share your new design system more broadly by configuring privacy settings for that specific design system.