Contextual design documentation for better designer-developer collaboration
To deliver delightful product experiences, strong collaboration is needed between design and development teams. Design Systems act as a key to collaboration, which encourages both teams to share a common ground and deliver efficient, consistent, and scalable products; however, design systems will have a heavy impact on development teams' velocity if they are treated like just another standalone reference tool.
Imagine a scenario where your development team receives a set of designs for implementation. To translate your design to code, they refer to a standalone design documentation site where they primarily copy + paste the code fragments and make alterations. On several occasions, this approach is frustrating because the documentation is generally overwhelming and pushes your developers to switch context several times between your design, the documentation site, and their favorite editor before getting it right.
I wondered why we don't deliver the design system documentation or at least a part of it as contextual help? We all know that contextual help limits our users' need to switch contexts and continue their task flows. In a quest to accomplish this, I explored several plugins of Sketch, Figma, and Adobe XD and finally settled with Design System Packages (DSPs) by Adobe.
What are Design System Packages (DSPs)?
Design System Packages (DSPs) are a new open-format folder structure created to help teams share design system information across tools. DSPs contain all the information developers need to consume while coding, including code snippets and documentation.
Who is responsible for Design System Packages (DSPs)?
The Designs and Development teams are responsible for creating, updating, and maintaining the Design System Packages.
The design team creates design elements such as color system, typography, form elements, layout, etc.
The development team maps the design elements with fragments of framework-specific code such as Angular, React, or Vue or with vanilla HTML, CSS, and JavaScript snippets.
How are Design System Packages (DSPs) consumed, and by who?
Development teams consume the Design System Packages. DSPs are delivered to the development teams through Adobe XD Extension for Visual Studio Code. This extension allows developers to map design sources created in Adobe XD and Creative Cloud Libraries, visually.
How does Design System Packages (DSPs) and the Adobe XD extension for visual studio code benefit me?
They can help accelerate your workflows.
The design team can create tokens based on designs with one click in seconds and generate a new or update existing design system package.
The development team can consume the design system package and quickly find design system information such as tokens and components without moving away from their favorite editor.
How do I create a Design System Package (DSP)?
Step One: Create a new Adobe XD Project
New to Adobe XD? Take a quick tour to learn what is Adobe XD and what is it used for?
Step Two: Create tokens for Colors, Typography, and add Components per your design
Step Three: Publish your project as a Library
After you’ve published your library, generate a sharable link.
Step Four: Install Adobe XD Extension for Visual Studio Code
- Open Visual Studio Code
- Go to Preferences -> Extension to open the extensions panel
- Search for Adobe XD
- Install the Extension
Note: To verify your installation, look out for XD extension on the lower right of your Visual Studio Code status bar.
Step Five: Create a Design System Package using Adobe XD Extensions for Visual Studio Code
- Launch the Adobe XD Extension from the status bar of Visual Studio Code
- Click on Create Package to create a new Design System Package
- Provide the Design System Package Name and Save Location
- Select the Target Language(s) from the available options. For our demo, I have selected SCSS
- If your library is Private, you need to authenticate with an Adobe ID. You can do it step at any point through the DSP settings page available in the extension.
- Provide the CC library link you have generated in Step Four and click on Import to continue.
If everything goes well, you will see the downloading complete message in your Visual Studio Code. All your tokens, typography, and components will be available on the side panel.
Step Six: Edit your Design System Package (DSP)
Edit your Design System Package (DSP) and provide additional documentation for your tokens, typography, and components. For this instance, I’ll be focusing on the components.
Editing Components
- Click on the package icon next to your DSP name on the side panel
- Click on Edit Package and Select the folder where you have previously chosen while creating the package
- Click on Start Editing available at the bottom of the side panel
- Select a component you’d like to edit and provide Code Snippet and any additional documentation the developer needs to know about this component. Repeat this process for the remaining components.
The snippet trigger in your components is responsible for triggering the contextual documentation when your developers launch the Visual Studio Code IntelliSense. You can modify the prefix (xd_ by default) from the DSP settings.
When you Finish editing, Adobe XD Extension for Visual Studio code automatically compiles the tokens for the target language(s) you’ve mentioned while creating your package. You can add more languages through DSP settings.
Note: Additional packages are required to compile the package to the target language(s). Visual Studio Code automatically prompts you to install the required packages in case they are missing.
How do I deliver Design System Packages (DSPs) to development teams?
Once you have created a DSP, you can deliver one of two ways;
- Share your DSP packages using EMAIL/Shared Drive etc.
- Share your DSP packages using NPM
It is recommended to deliver your DSPs via NPM. Learn more about publishing DSPs to NPM.
How will they (development teams) consume Design System Packages (DSPs)?
For this instance, I’ll be focusing on consuming the packages via offline upload. In general, it is recommended to load your DSP packages using NPM.
Step One: Open Visual Studio Code and Launch the Adobe XD Extension
Step Two: Consuming Design System Package
- Click on Load package and select the folder where you’ve downloaded the package.
- Review the tokens available with the package and click on Finish to continue.
If everything goes well, you’ll see the DSP packages content in Visual Studio Code.
Step 3: Verifying with IntelliSense
- Create a .HTML document and add the required HTML skeleton
- Start typing xd_ to view the preview of components and their documentation available with the Design System Package.
- Select an option from the IntelliSense drop-down to replace the text with an actual code fragment, and you are done!
In a nutshell…
Design systems are the link between design and development teams, and our developers are its fundamental users. The design system documentation is a single source of truth they follow to convert our designs to code. As designers, we must focus on their experience, understand their pain, and make our design systems more contextual and easier to consume.
