Single source of truth is a lie
In the design system world, there’s some debate about where the source of truth lies. Is it code? Figma? Is it really singular? Before we can answer any of that, we need to get on the same page about what we mean by truth.
We do love a clear answer. The whodunnit that ends in a plot twist with undeniable evidence. The youtube video of the right way to open a pomegranate. Like a strong focal point in an image, truth can bring comfort and peace; a moment of calm. It gives us clarity so we can move on with our lives. But in a complex space like design systems, truth can quickly become muddled or stale. ‘Simple, right answers’ can quickly morph into ‘general best practices with several known exceptions that we’re planning to document soon’.
How might we refine truth and information architecture to promote peace and comfort at work?
Truth is in the eye of the beholder
To some, truth means how things in our product should be. Design and documentation is the final word in this mindset. If design and code are different, the code needs to change.
When a designer needs to know what a component can and shouldn’t do, they pull up the component documentation. When a developer needs to check they’ve got the latest token package installed, they reference release notes documentation. When a QA tester checks a new component for our next design system release, they reference the designs and requirements to make sure everything is working as it should. In this case, design and documentation are used to gauge code accuracy and guide proper usage.
Even in this mindset, though, this is being too simplistic. When we find differences between design, code and documentation, the very next question is, who is right? The answer varies quite a bit. Sometimes the designs have it right, sometimes it’s the code. Sometimes both are wrong and we documented a decision that was never holistically implemented. Tasty food for the backlog.
Truth is in the eye of the customer
To others, truth means what’s actually in the hands of customers. Production code for the win. At the end of the day, it doesn’t matter what the designs and documentation say. It only matters what our customers are experiencing on a daily basis. Customer sentiment is the ultimate truth and everything else needs to change in service of that. Of course this assumes we’re accurately gathering metrics.
We might brag about how awesome our system is and how accessible and personalized our products can be, but if the customer’s experience is confusing, none of the rest matters. If customer sentiment is what we’re after, we can write reams of guidance without moving the needle one bit. The product begins with designs and documentation, but the source of truth is what’s in the market today.
Truth is in your hands
Tactically, truth can mean both of these concepts combined. It means where product teams go to find the information they need to create things that lead to success. Teams need to understand the current state of the product. They need to understand metrics and sentiment. They need to be able to quickly find answers to use the design system in the right ways. They also need ever-improving tools that guide their creation process and automate decisions.
From a design system perspective, our coded components are a source of truth because they get used to make tangible customer experiences. But design assets, documentation, testing and quality-boosting tools also impact how quickly teams can deliver consistent and robust experiences.
The design system team might make a plugin to guide designers towards better file hygiene. This makes it easier to keep things tidy, and easier to share between projects and the design system libraries. The source of truth for proper file hygiene becomes the function of the plugin.
Singularity, meet Ecosystem
So, before we can arrive at a single source of truth, we need to agree on our terms. Truth can be viewed from many vantage points, so we need to make sure we’re defining our terms. In many cases, a single source of truth is less important than a cohesive ecosystem of organizational knowledge. Information will live in documentation, but it will also be tucked nicely into Figma to guide designers right where they work. Some will pop up when it’s needed through tools like Typescript during coding. The important thing is that truth finds a home that shows up logically on the map.
Hunting for a single source of holistic truth feels reductionistic to me. In reality, teams need truth to live in many places to be absorbed and used at the right time. That’s how we connect the source of truth to the experience a customer lives with at the end of the day. Finding that truth naturally and quickly is how we can promote peace and comfort at work.
