What the System Is Trying to Tell You

Every design system audit starts the same way. You open the file expecting to spend an hour taking notes, and two hours later you're still pulling on threads, finding components that reference tokens that don't exist, naming patterns that changed midway through a project and never got cleaned up, documentation that describes something nobody builds anymore. The gap between what the system says it is and what it actually is turns out to be wider than anyone told you.

This happens on almost every audit. It isn't a sign that something went badly wrong. It's a sign that a team kept shipping.

The decisions that look careless in retrospect usually weren't. The hardcoded value was a deadline call. The duplicated component was a product team that needed something slightly different and didn't have time to loop in the system team. The naming inconsistency is from a rebrand that got partway through before priorities changed. We've worked with systems that looked completely unstructured at first glance and turned out to have a clear internal logic once we understood the product constraints driving them, constraints that were never documented because the team living inside them didn't think to. Auditing a system without that context is like reading someone's notebook and concluding they're disorganized because they crossed things out.

What you find in an audit is a record of constraints, not a catalog of failures. The team that built it was working with the information they had, under the pressure they were under, for the product they were trying to ship. Reading it that way changes everything about how you report back.

The practical version of this is straightforward. Before you present findings, ask yourself whether the person who made each decision would recognize your description of it. If your summary makes something sound like negligence that was actually a reasonable call under pressure, the report isn't accurate yet. Accuracy here isn't about being soft, it's about being useful. A finding that a team can act on is one they understand, and teams don't act on findings that make them feel like defendants.

Sequencing matters too. Leading with everything that needs fixing is the fastest way to put a team on the defensive, and a defensive team doesn't absorb feedback well. In practice this might mean opening with the token architecture that's held up surprisingly well across two years of product changes, or the component structure that clearly had some considered thinking behind it, before getting into what needs work. It gives the team somewhere to stand while they take in the harder findings, and it tends to make the conversation more productive than starting from a list of problems.

None of this means softening what you find. Some systems have real structural problems that need to be named directly. But there's a difference between being direct and being blunt in a way that closes down the conversation before it's started. The audit is the beginning of the work, not the end of it. How the team receives it determines what happens next.

It's something we come across a lot in our work with teams. If you're working through something similar, we'd love to hear where you're at and see if we can help.

Thanks for reading, and see you next week! 👋💛
– The Baseline team