Capturing your design system decisions

Architecture Description Records (ADRs) are often used in enterprise or platform-led businesses to keep track of new technology or methodology proposals. They document not just whether a proposal was accepted or rejected but the context around that decision. ADRs can prompt an understanding of the benefits and risks of a choice. If we were to backtrack on a decision we’ve made, could we get a sense of the impact of that before we implement it?

I think there’s something in this that we could use more broadly than just in tech or engineering, perhaps as Design System Decision Records that encompass all related disciplines. Creating or updating a design system involves making decisions that inform our tooling, workflows, and output. We often rely on team members’ memories of what has been tried, when, and the outcome. This lack of context can either lead to retreading the same ground or fear of trying something new, as there may be little context regarding how the system got to the state you find it in.

Context matters

This context matters in how we capture the decisions made. If we accept that decisions are made in good faith based on what was known at the time, even if they turn out to be wrong later, this context helps. If the circumstances around that original proposal have changed, we need to be aware of that, not just that a colleague may have submitted a similar proposal before.

Far from being etched in stone, design systems change and often evolve, even in small ways, as the people supporting it gain more experience and have different challenges to face. Using these decision records can clarify how the system was when certain choices were made or when proposals were rejected. It also works as part of onboarding new people to the team, knowing they can determine the reasons for certain choices.

If we look at Google’s or Amazon’s guidance on how to write ADRs, we can take something from this that applies to any kind of decision we might make. Amazon’s example ADR is something we could riff off:

Example Design System Decision Record

Title: This decision defines our use of design tokens
Status: Accepted
Date: 3rd February 2023
Author: Dan Donald

Context
So far, the process between design and development has involved developers needing to select values from our design files. We need a better way of ensuring the values are easy to find and to keep consistent.

Decision
We’ll start with foundational tokens for colors and typography, as these are our current pain points. We’ll implement these with Tokens Studio and sync them with our GitHub repo.

Consequences
Positive:

• Tokens will ensure that design decisions are stored in an interchangeable format and used by everyone

Negative:

• Adopting tokens will involve supporting everyone and changing how they work.

Compliance
We should follow the emergent W3C community group spec for design tokens.

Notes
X and Y in Team Z have done a proof of concept that validated the approach, and we’re happy this is the right direction for us.

This example doesn’t feel like much of an overhead for changes of any significance. It also provides our future selves or colleagues with some history and context. Spotify has this great reference discussing when you should write and ADR – basically, most of the time!

An adaptable tool

Much like any tool or process, we can adapt this idea of Design System Decision Records to fit our needs. The important thing is that they provoke thought as we capture that moment. More than that, you can capture decisions that have already been made if this concept works for you. Start now and document the hows and whys of your design system as it is!

This kind of content makes a lot of sense to be collated in your documentation and could include links to any components or code they reference. Vice-versa, as links back to it, can be relevant when reading the docs of a given component.
See if they work for you, and let me know your thoughts or any other ways you’ve tried capturing decisions you’ve made on our Slack community, zheroes!