ADR-Driven Design Systems: If It's Not in a Record, It Didn't Happen
I design and scale structured Design Systems across complex products.
Currently exploring how AI fits into system architecture — not as a replacement for thinking, but as a multiplier for structured workflows.
Interested in governance, token architecture, documentation systems and operational design.
Writing about experiments, lessons learned and practical implementation.
Every design system has technical debt. Most of it isn't accidental — it's the result of decisions that were never documented.
Someone chose 8px spacing over 4px. Someone decided semantic tokens shouldn't cover elevation. Someone picked "ghost" over "tertiary." These decisions happened in Slack threads, Figma comments, or standup calls. Six months later, nobody remembers the reasoning.
Architecture Decision Records fix this.
What an ADR Is
A short document capturing one decision: what was decided, why, what alternatives were considered, and consequences. Borrowed from software architecture, adapted for design systems.
One decision per ADR. Numbered sequentially. Once accepted, never edited — if the decision changes, a new ADR supersedes the old one.
Why Design Systems Need ADRs
Code is partially self-documenting. Design systems aren't.
color.action.primary.default doesn't tell you why three layers instead of two. A Button with five variants doesn't explain why "Ghost" exists but "Outline" doesn't.
Without ADRs, every new team member guesses at reasoning. Different people guess differently. Inconsistency follows.
My Template
Design-system-specific differences from generic ADRs:
- Tags — controlled taxonomy (tokens, components, governance, migration, tooling)
- Implementation split — separate Figma and code concerns
- Governance section — ownership and review process
- Migration — always addressed, DS rarely starts from zero
- Source of truth — explicitly named
Structure: Header (number, status, date, deciders, tags) → Context → Decision → Consequences (positive, negative, migration) → Implementation (Figma, Code, Governance) → Alternatives Considered.
Status: Proposed → Accepted → Deprecated or Superseded.
Tag Governance
2-4 tags per ADR, minimum 1 artifact tag. No ad-hoc tags. New tag category = new ADR.
Artifact: tokens, components, patterns, layouts, theming, css. Process: governance, migration, tooling.
Example: ADR-001 — Token Architecture
Context: Tokens inconsistently named, duplicated between Figma and code, can't scale for multi-brand or dark mode.
Decision: Three-layer model (base → semantic → component). Base + semantic in Figma Variables. Component tokens in code. Naming: {category}.{property}.{variant}.{state}.
Consequences: Theming = semantic remap (positive). Existing flat tokens need migration (negative). Two-sprint deprecation period.
Alternatives rejected: Flat model (doesn't scale), two-layer (blurs ownership), Tokens Studio as source of truth (adds dependency).
This ADR gets referenced in every subsequent token discussion. "Why can't I use the hex value?" → "ADR-001." Debate doesn't repeat.
Governance
Anyone can propose. Review: DS Lead + Tech Lead. Breaking changes to semantic tokens: mandatory 2-cycle deprecation.
Operational tracking: SharePoint Decision Log (from my governance post) links to full ADR. Log = notifications. ADR = reasoning.
Common Objections
"Too much overhead." ADR: 15 min to write. Repeated debate: 30-60 min each time. After 2 repeats, ADR paid for itself.
"We're too small." If >1 designer and >1 developer consume your tokens, you need documented decisions.
"Can't AI generate these?" Partially. I use Claude for ADR drafts. But the decision — the judgment — is human.
Getting Started
Write ADR-001 today. Pick the most debated topic. Document the decision. Use whatever template works.
After five ADRs, new discussions start with "have we already decided this?" instead of zero. That's the compound return.
Part of a series on DS architecture and AI-assisted workflows. Token architecture from ADR-001 was detailed in the previous post.
