7 min read
|
Saved February 14, 2026
|
Copied!
Do you care about this?
The article emphasizes that Design Tokens alone can't capture the reasoning behind design choices. It introduces Architecture Decision Records (ADRs) as a tool to document the "why" behind decisions, helping teams avoid confusion and maintain clarity over time.
If you do, here's more
Design Tokens alone don’t suffice for effective design systems. They reveal what decisions were made but fail to explain why those choices were necessary. The author shares experiences that highlight the confusion arising from undocumented decisions. Designers often find themselves questioning previous choices, especially when those who made them are no longer available. The lack of documentation leads to uncertainty and inefficiency, as decisions become obscured over time.
To address this issue, the author advocates for using Architecture Decision Records (ADRs). These records capture the reasoning behind design decisions, acting as a “why we did this” diary. Unlike design tokens, which detail what was created, ADRs explain why specific choices were made. This documentation can clarify complex naming conventions and component decisions, enhancing overall system understanding. The author provides a straightforward ADR template that includes sections for what was learned, why it matters, implementation notes, and where the information is documented.
An example illustrates the utility of ADRs. The author advises against using hierarchy terms like "primary" and "secondary" in design tokens because their meanings can shift depending on context. Instead, they suggest using terms based on visual emphasis, leading to clearer communication and better scalability. The article emphasizes simplicity in maintaining ADRs, recommending regular updates and reviews to keep the documentation relevant and accessible. For solo designers, integrating ADRs with tools like LLMs can streamline their workflow and ensure consistency in decision-making.
Questions about this article
No questions yet.