Design Tokens aren’t enough. Architecture Decisions need a place in your Design System.
TL;DR: I’m sharing a simple Architecture Decision template for documenting the why behind your design system decisions.
Hi Designer 👋 Sam I am here.
It’s confession time. I used to believe that Design Tokens were all I needed to document my design decisions. Until I was working with a new client and had one of those classic WTF design-system moments, and realized Design Tokens aren’t enough. They describe WHAT the design decision is, but not WHY it was made.
“Why is the primary button using the quaternary brand token? WTF is quaternary anyway?” 😳
Let’s be honest - we’ve all inherited (or created 🙈) systems where you end up confused and frantically searching Slack for who to ask “why did we do this? Is there a technical reason, or is this an issue we need to fix?”
Sometimes the answer is “I don’t know, the person who did that isn’t here anymore.”
Or “That’s a legacy decision we haven’t fixed yet.”
Or “I’m not sure, you might want to check with Mackenzie about that.”
Usually, by the end of my fact-finding mission, I discover that the decision was made for a very good reason at the time, but it no longer makes sense.
The problem is, we forget why.
I’ve definitely been that person who made a decision, didn’t document it, and then, three months later, was staring at my own token structure, going, “why did I do this?”
I once spent an entire afternoon reverse-engineering my own naming convention because past-Sam apparently thought future-Sam would just remember by looking at the token names. Spoiler: she did not. 😅
So the problem isn’t that we make bad decisions. The problem is that we don’t write them down, and then we forget.
And that’s totally normal, because our brains weren’t designed to remember every little choice we made three years ago (or honestly, three weeks ago if you’re anything like me).
The good news? This problem is mostly avoidable.
One of the best tools to prevent it is something developers have been using for years: Architecture Decision Records (ADR).
They’re basically a living record of why they made technical choices in their codebase. Not what they built - that’s in the code itself. But why they built it that way.
I get it. “Architecture Decision Records” sounds very engineering-y. Very formal. Very... not design?
But design systems are complex. Like, really complex. We’re making naming conventions, token hierarchies, component API decisions... All stuff that has huge downstream impacts. And just like in code, those decisions fade from memory.
So for design systems, the ADR captures the reasoning behind your decisions - the stuff that isn’t obvious from looking at your Figma file or your token structure.
What is an Architecture Decision Record?
An Architecture Decision Record (ADR) is a living decision log (basically a “why we did this” diary) and template you (or an LLM) can complete each time you make a decision about a part of your design system:
Captures what you figured out
Explains why it matters to your system
Gives specific examples and exceptions
Points to where it’s actually implemented
It’s different from:
Your design tokens (that shows the what)
Your component documentation (that shows the how)
Meeting notes or Figma comments (too scattered, too temporary)
It’s the why behind patterns that aren’t immediately obvious. Like:
Why you use
name-wrapperinstead ofwrapper-namein your component layersWhen to create a new component vs adding another variant.
Why quaternary is now on the restricted list in your naming conventions doc.
And here’s something I’ve learned - this document isn’t just for humans. It’s also super valuable for LLMs working with your system. But let’s get to that in a minute.
Template and examples
Okay, so you’re sold on the idea. What do you actually write in this thing?
Here’s the Architecture Decision Record template I use. It’s deliberately simple - you don’t need anything fancy to make this work.
## [Pattern or Decision Name]
**Last updated:** YYYY-MM-DD
**What we learned:**
[The discovery or principle - what pattern emerged]
**Why it matters:**
[Impact on consistency, clarity, implementation, or maintenance]
**Implementation notes:**
[Specifics, edge cases, exceptions to the rule]
**Documented in:**
[Where this lives - Airtable table, token files, component docs, etc.]
Let me show you an example from my Future Friendly UI system to make this concrete:
No Hierarchy Words in Design Tokens or Components
Last updated: 2024-11-15
What we learned:
Avoid primary, secondary, tertiary, quaternary as token or component names. These hierarchy terms describe relative importance that shifts based on context, not intrinsic visual properties. For example, when the preferred action as the “primary” button needs subtle styling, the name contradicts the implementation.
Why it matters:
Context breaks meaning: A “tertiary” button alone becomes the primary action in that context. Place “secondary” and “tertiary” together, and secondary becomes the primary intended action.
Names should be stable:
strong,standard,subtledescribe visual emphasis that doesn’t change based on the context of how the component is being used.Scales better: You don’t have to invent “quaternary” or “quinary” - emphasis scales are finite and descriptive.
The alternative - emphasis naming:
strong- high visual prominencestandard- default visual weightsubtle- reduced visual prominence
A strong button is always the primary intended action when placed next to standard or subtle. A standard button becomes primary when paired only with subtle.
Exceptions:
Client vocabulary alignment: If the team calls their logo color “brand primary,” that’s fine - it matches their mental model.
The smell test: If you’re reaching for
quaternary, you need a different naming scale that focuses on emphasis or intended use case instead of hierarchy.
Implementation notes:
This applies broadly across the token system - component variations, color scales, typography hierarchy. It’s a general principle, not a rigid rule.
Where applicable, use emphasis and intent descriptors instead:
✓
action.button.brand.strong✓
action.button.neutral.subtle✗
action.button.primary✗
action.button.secondary
Documented in:
Token naming conventions guide, component token structure in Airtable base “DS | Naming is hard”
Working with an Architecture Decision Record
The key is to keep it simple! You can work with an Architecture Decision Record as a collaborative document:
Google Doc stored in your team’s Google Drive
Markdown file stored in a code repository
Miro or FigJam file
Less desirable option for team members who don’t use these tools won’t have access to them.
Each time you make a decision:
Duplicate the template in your ADR document and
Add the decision.
Update the version number of your document.
Each month, or at the end of a sprint, review the document and move essential documentation to its permanent location.
In the recording below, I’m using Obsidian to create a new record in my ADR in markdown. If you aren’t yet writing your notes as markdown files, Obsidian is an excellent tool with lots of powerful features, and its free!
For the design-team-of-one folks out there who don’t have a team to collaborate with (hi, I see you 👋), add your ADR to your favourite LLM as a project file!
I love using Claude Desktop as my personal, on-demand development partner in my projects.
Each time we work through a decision, I ask Claude to update the ADR for me!
At the beginning of each new chat, I prompt it to read the ADR to get up to speed. This prevents suggestions like “call it the quaternary button” because Claude knows that’s not allowed in this design system and why.
The Future Friendly Design bonus of an ADR
Future friendly design is all about what you do today that sets you up for success in the future, based on the knowledge of what’s worked and not worked well in the past.
Having the reasons why a decision was made documented within the design system is really helpful in the future:
Clients or team members who need to get up to speed
Future you, who will definitely forget why your engineer convinced you that
action-passive-subtle-activewas an acceptable token name 🙈LLMs who are pattern-recognizing engines that need this additional context about your unique decisions to ensure consistency
In fact, I asked Claude, “Please explain to me, like I’m a new team member, what an architecture decision document is and why it is important to your workflow with me as an LLM.”
The response summed it up perfectly:
Think of me as a really capable assistant with short-term memory loss. Every time you start a new chat, I forget our previous conversations. I can search past chats, but that’s slow and inefficient.
Real Talk
Let’s be honest, we’ve all started documentation that we never kept up with. Here’s how to not let that happen with this:
Document decisions when you make them, not later
The moment you’re discussing “should this be X or Y?” - that’s when you document it. Not next week. Not when you have time. Right then, while the reasoning is fresh.
If you’re working with an LLM, this is even easier - just ask it to add the decision to the doc as part of your working session.
It’s okay to start small
You don’t need a bajillion entries.
Start small. Start by writing down why you made one decision this week. Then another. Then another.
Six months from now, when you’re staring at your system wondering “why did I do this?” - you’ll have the answer. And honestly, that’s a pretty great feeling.
Update dates, don’t delete history (unless you really need to)
When a pattern changes, update the date and add notes about what evolved. Sometimes it’s helpful to see that history. But if something is truly obsolete or conflicting information that could cause more confusion than clarity, go ahead and remove it.
Make it searchable
Whatever tool you use, make sure you can search it quickly. When you’re mid-work and need to remember “what was our rule about wrapper naming again?” - you should be able to find it in like 10 seconds.
Having my Architecture Decisions Record in a Claude Project means I can ask the LLM to find the answer for me! I also have my GitHub repo of Design Tokens synced to the project and MCP access to Airtable and Figma so Claude can pull up examples from my system as needed.
Download Sam’s Architecture Decision Record Template
Markdown File - Download from my GitHub Repo.
Did you get the ick when you read GitHub? 😳 It’s not that scary, I promise!
What’s Next: More Future Friendly Foundations
This architecture decision record is just one piece of what I call the future friendly foundations for design systems. In a world where LLM-assisted workflows are becoming the norm, our design systems need more than just colors, spacing, typography, and motion.
The other pieces that help avoid those WTF moments:
Systems maps showing how information flows
Token structure documentation explaining your hierarchy
Component relationship diagrams showing how everything connects
Naming patterns, conventions, and syntax documents
I’m planning to cover each of these in upcoming posts. (And hey, if you’re coming to one of my upcoming workshops, we’ll dig into some of this there too.)
Now go write down why you did that thing. It’s not too late to start! Future you is going to thank you for it 🫶
If you want to chat about this or share how you’re documenting decisions in your system, come find me!
Neat. How do you link those straight from the tokens file into the .md file, so you can jump to the reasoning behind each token right away instead of doing a manual search and find?