DX: Developer Experience in Design Systems
DX, or Developer Experience, is a discipline that describes the experience of a developer using a product. In a similar way to UX (User Experience), a good DX makes all the difference in your product’s reach potential, be it an API, a library, a tool or a service. The awareness on this subject has grown so much that there is even specialized work — dev Sarah Drasner’s Twitter bio says “Head of DX @ Netlify”.
In my experience developing Astro, Magnetis’ design system (my former employer), the quality of DX is very relevant to boost user productivity. These people may or may not be Magnetis employees, since Astro is open sourced — which means that the responsibility is even greater.
Based on what I learned there, I bring some attention points to improve the DX of your project:
1. Documentation
It seems somewhat obvious to mention documentation as a main point of attention in DX; but, for an artifact that will often be the only means of communication with the user, it rarely receives the attention it deserves.
In open or closed projects and repositories, some maintainers expect users to understand everything just by reading the code — which is not only bad communication, but also bad empathy. And within teams, the solution to poorly documented projects is often to ask someone, which is also not productive for both sides.
Documenting is your opportunity to explain in human language the purpose and how to use your project. Here, you must teach how to use the design system, but also how to contribute to its code (even if it is not open sourced, newcomers might join the project at any time). Think of these moments separately — you can even create two separate files on GitHub, as we did in the Astro repository with “Readme” (usage guide) and “Contributing” (contribution guide).
I will not go into detail on how to write good documentation because I have already written an article about it, but, in summary, it should include three things:
- Comprehensive: Make sure the document covers any doubts that may arise about how the project works. Explain what it does, how to install, how to use it, and include solutions to known problems. Your goal here is to eliminate the need to contact you directly to answer any questions. Don’t be a bottleneck. The Single Source of Truth must be the documentation, not you.
- Accessible: Don’t assume that everyone who reads the document has the same technical level as you, even if you think you have a low technical level (I’m looking at you, impostor syndrome). Avoid technical terms when possible. Write step-by-step tutorials. Do not assume that the person knows how to clone a project or install dependencies via terminal, for example. Explain to a beginner and you will be explaining to everyone.
- Friendly: Reading documentation can be a tedious activity, so try not to make it unnecessarily long. There is a difference between comprehensive and wordy. Get to the point, use a friendly tone and, if you want to, you can even add a touch of humor.
2. Usage patterns
In the case of Astro, the design system is used by applying CSS classes to a markup structure showcased in the documentation. Here’s an example:
We tried to create class names that are descriptive for humans, instead of something like a-bt--ur__md1, even if they’re longer; we want them to be self-explanatory and memorable, which reduces confusion and the need to consult the documentation repeatedly.
By the way: this is when you realize you’re doing API design. Neat!
Another important point is that class names need to be more specific (like a-btn) rather than completely generic (like btn) to avoid conflicts with existing CSS in legacy projects. The objective is to minimize side effects when importing the design system, and this mindset must be applied to all user-facing (the dev being the user here) points of the project.
Finally, to create a scalable and predictable system, you need to try to maintain a usage pattern that makes sense. This is a big challenge when we receive design demands that are outside the norm, and it may be necessary to negotiate to satisfy these demands while also maintaining consistency.
For example: in Astro, there are many variants of button styles and each one has four colors. A design system tends to scale, and when new colors or styles are introduced, we wanted to follow the pattern and even make it easier to manipulate these buttons with less visits to the documentation.
With that in mind, we created a class structure that varies in a predictable way. a-btn--uranus is the primary button in blue (color we called “uranus”). For the other variants, we added a modifier that can be a-btn--outline-uranus for the outline button or a-btn--ghost-uranus for the ghost button.
Furthermore, the color “uranus” can be replaced with any of the color variants (“mars” for red, “venus” for pink or “earth” for green) in any button and the result is still predictable.
And to define size, the user must add one of the three size classes: a-btn--small, a-btn--medium or a-btn--large. Regardless of which button, the result is always the same.
Here’s a video of me playing around with these modifiers (please open in a new tab):
By creating standards and predictability, usage is more intuitive, error-proof and more independent of documentation.
3. Technologies
Aside from the ground we just covered, good DX criteria still include the consequences of technical decisions, such as difficulty level, package size and barriers to use or contribute.
Please value pure simplicity and avoid unnecessary complexity. Sometimes, we really need new tools to scale the project. But make sure to question if that’s really necessary. For example, if it is possible to write CSS without any frameworks, write it — it is more feasible than it looks. Each layer that we add to the stack can create a barrier for those who don’t have context of that specific technology; we are often not aware of that, because it looks familiar to us. It’s a matter of empathy and inclusion, but also of allowing more people access to your project, by using or contributing.
Try your best not to weigh down your project with dependencies. Each of them requires updates in the future, which can break the project and generate work to adapt it, in addition to being a potential door for vulnerabilities. Don’t lose control.
Keep trying to automate as many manual processes as you can. For example, instead of asking to import typographic fonts or icons manually, include them in the project package and create simple ways to call these assets. Aim for the concept of “zero configuration”.
Test the speed to download and run the project, and look for improvements in this process as well.
4. Update guides
Astro once released version 2.0.0 with breaking changes — that is, with incompatible changes that can cause breaks in the projects where the dependency is installed. In that case, the reason was that some CSS classes and some icon names were changed.
Updating a dependency in these conditions requires careful adjustments to the project in order to avoid unpleasant surprises. What can you do to improve DX?
- Always be mindful of changes that can cause breakage and weigh the benefits before proceeding. Plan the new version to isolate the incompatibility and cause minimal side effects;
- When you release this version (which will be major, according to Semantic Versioning), write an Update Guide mapping all the changes that developers need to make to their projects that use the design system. See Astro’s v2.0.0 Update Guide here as an example.
In conclusion, a design system (or any project) with good DX is a system that’s easy and pleasant to use and contribute. With equal parts of technical quality and clear communication, it is possible to create an experience that generates less stress and makes life easier for developers on your team, and even for other teams out there.
