Refactoring UI

In one sentence

To build scalable products, you must stop designing "screens" and start architecting "systems" by decomposing UI into granular, tokenized components that can be audited, refactored, and reused.

Why read this (and who it's for)

This book is for the designer who feels overwhelmed by the sheer volume of screens in a growing product—the designer who finds themselves redesigning the same button style five different ways because there isn't a "source of truth."

It solves the Scale Problem: how to ensure that a design remains coherent when it grows from three screens to three hundred. After reading this, you will move from being a "pixel pusher" (someone who creates unique layouts) to a "Systems Architect" (someone who builds the vocabulary and grammar of an interface). You will learn how to audit your existing UI, extract its DNA into tokens, and build a library that actually survives the chaos of real-world production.

The big idea

The authors argue that most UI design fails not because designers lack aesthetic talent, but because they treat design as a linear process (Screen A $\rightarrow$ Screen B $\rightarrow$ Screen C) rather than a systemic process. When you design linearly, every new screen introduces the risk of inconsistency. If you change a brand color or a border radius on one screen, you have to manually find and update every other screen. This is "Technical Debt" in the world of design.

The solution is Refactoring. In software engineering, refactoring means restructuring existing code without changing its external behavior—making it cleaner, more efficient, and easier to maintain. Wathan and Schoger argue that UI design must undergo this same transformation. You must decompose your UI into its smallest constituent parts (Tokens), assemble those into building blocks (Components), and organize those into behaviors (Patterns).

By shifting the focus from the output (the screen) to the input (the system), you create a "Design Language." When the system is robust, adding a new screen becomes an act of composition rather than creation. You aren't inventing a new button; you are selecting a pre-existing component and configuring it with existing tokens. This allows for massive scale because the "rules" of the UI are baked into the foundation, not repeated on every page.

Key ideas

Design Tokens: The DNA of the System

What it is — Design tokens are the smallest atoms of meaning in a design system. They are the primitive values—like colors, spacing, typography, and shadows—abstracted away from their specific usage (e.g., instead of blue-500, you use color-action-primary). Why it matters — Tokens allow for instantaneous global changes. If your brand moves from "Electric Blue" to "Deep Teal," you change one token value, and the entire system updates automatically. It removes the ambiguity of "what blue are we using here?" In the book — The authors illustrate this by showing how a hard-coded hex code is a "dead end." They advocate for a naming convention that describes intent (how it's used) rather than appearance (how it looks), ensuring that when a designer chooses a token, they are choosing a role within the system.

Componentization and Hierarchy

What it is — This is the process of breaking down UI into reusable building blocks based on their responsibility. It follows a hierarchy: Atoms (buttons, inputs), Molecules (search bars, cards), and Organisms (navigation headers, feed items). Why it matters — It prevents "Design Bloat." When you build a component once, you ensure that every instance of that component behaves identically. It also allows for "Single Source of Truth" updates: fix a bug in the button component once, and it's fixed everywhere. In the book — The authors walk through the evolution of a UI element from a one-off design to a standardized component. They emphasize that a component is only useful if it is reusable. If you only use a component once, it’s not a component; it’s just a messy layout.

Consistency vs. Flexibility (The Tension)

What it is — A perfect system provides total consistency, but a perfect product requires flexibility to solve unique user problems. The goal of Refactoring UI is to find the "sweet spot" where the system provides enough constraints to ensure coherence while allowing for enough variance to satisfy specific needs. Why it matters — If your system is too rigid, designers will "break" it by creating one-off exceptions that don't follow the rules. If it’s too loose, the product becomes a fragmented mess of different styles. In the book — The authors discuss how to handle "edge cases." They suggest that when a unique requirement arises, you shouldn't just make an exception; you should evaluate if that requirement signals a need for a new component or a new variant in the existing system.

Documentation as an Interface

What it is — Documentation isn't a manual you write at the end of a project; it is the interface through which other designers and developers interact with your system. Why it matters — A design system is useless if people can't find what they need or don't understand how to use it. Good documentation reduces friction, prevents "rogue" designs, and ensures that the system scales without constant Slack messages asking "how do I do X?" In the book — They argue for "living documentation." This means moving away from static PDFs and toward interactive guides (like Storybook or Figma files) where the documentation lives alongside the actual components.

Accessibility as a Constraint, Not a Checklist

What it is — Accessibility should be baked into the tokens and components from day one, rather than being an audit performed at the end of the design cycle. Why it matters — Retrofitting accessibility is expensive and often results in "ugly" fixes. By making accessibility a core constraint (e.g., ensuring all tokens meet contrast ratios), you ensure that every component produced by the system is accessible by default. In the book — The authors show how certain design decisions—like color choice or touch target size—are actually accessibility decisions in disguise. They argue for "Inclusive Design" where the system's ruleset enforces these standards automatically.

Frameworks & tools

The Tokenization Workflow

Use this to move from a messy UI to a structured system:

1. Audit: Take an existing screen and identify every unique value (color, font size, spacing).
2. Categorize: Group these values by type (e.g., "Spacing," "Elevation").
3. Abstract: Rename the values based on intent. Instead of radius-8, use radius-button.
4. Map: Create a master list of these tokens. This is your "Source of Truth."
5. Implement: Replace all hard-coded values in your design files with these tokens.

The Component Evolution Cycle

When you encounter a new UI requirement, follow this loop:

1. Discovery: Identify the specific user need (e.g., "I need to show a progress bar").
2. Prototype: Design the best solution for that specific screen without worrying about the system yet.
3. Refactor: Look at the prototype. Can it be broken down into existing components? If not, what new building blocks are needed?
4. Standardize: Once the design is approved, "refactor" it into the library. Create the component, document its variants, and publish it.
5. Iterate: Every time you use that component again, you are now composing, not creating.

Memorable examples & stories

• The Button Evolution: The authors describe how a simple button can morph into dozens of variations (primary, secondary, disabled, loading). The lesson: Don't design "a button"; design the logic of what a button can do.
• The "One-Off" Trap: They describe designers who create a beautiful custom layout for one page, only to find themselves recreating that same layout on five other pages because they didn't take the time to "refactor" it into a component first. The lesson: If you're doing it twice, it should be a component.
• The Documentation Gap: A story about a team where designers were constantly asking developers how a specific margin was implemented because there was no documentation. The lesson: Documentation is the "API" of your design system; if the API is poorly documented, the system won't scale.

Key quotes

• "Design systems are not about making things look consistent; they are about making things easy to build." (Paraphrased)
  • Why it matters: Shifts the focus from aesthetics to engineering efficiency.
• "If you find yourself designing the same thing twice, you haven't built a system yet." (Paraphrased)
  • Why it matters: A litmus test for whether your components are actually reusable.
• "Tokens are the DNA of your UI." (Paraphrased)
  • Why it matters: Highlights that every visual choice flows from these foundational values.

How to apply it

This week

1. Audit one screen: Take a single complex screen in your current project. List every unique color, font size, and spacing value used on that screen.
2. Identify "The Orphans": Look at those values. Which ones are used only once? Which ones are repeated?
3. Create a Mini-Token Map: Create a simple spreadsheet or Notion page listing the 10 most common colors and spacings from that audit. Give them names based on intent (e.g., surface-primary, text-body).

Ongoing

• The "Component First" Rule: Before you start designing a new screen, ask: "What components do I already have that can solve this?" Only design something new if the existing system cannot satisfy the requirement.
• Refactor as you go: Every time you finish a screen and notice a repeated pattern (like a specific way of showing a 'User Profile' card), stop. Take 30 minutes to "refactor" that pattern into a formal component in your library before moving to the next screen.
• Tokenize everything: Never use a hex code or a raw pixel value in a final design file. Always reference a token.

Common pitfalls

• Over-Engineering: Trying to build a "perfect" system for a product that only has two screens. You don't need a complex token system if you aren't scaling. Start small and refactor as you grow.
• Token Bloat: Creating tokens for every single variation (e.g., color-button-blue-light, color-button-blue-medium). This leads to "decision paralysis." Keep the token list lean and rely on variants of components to handle specific needs.
• Documentation Rot: Writing documentation once and never updating it. If the documentation doesn't match the actual Figma file, designers will stop trusting it and go back to making one-offs.

Connects to

• Atomic Design (Brad Frost): Provides the structural hierarchy (Atoms, Molecules, Organisms) that Refactoring UI operationalizes into a workflow.
• Design Systems (Various): While many books talk about "Style Guides," this book specifically focuses on the Engineering aspect—how to refactor and maintain those systems over time.

If you remember only three things

• UI design is an engineering problem of systems, not a linear process of screens.
• Design Tokens are your source of truth; they allow for global changes by abstracting values into "intent."
• If you find yourself designing the same thing twice, it’s time to refactor that pattern into a reusable component.

Internalize it

• Reflection questions —

  1. Look at your current project's Figma file: How many different shades of "Grey" are currently being used? Why hasn't this been consolidated into a token?
  2. Think of the last screen you designed. Could you have built it using only components from your existing library? If not, what was missing?
  3. Is your documentation actually helping people work faster, or is it just a graveyard of screenshots that no longer match the live product?

• Flashcards — Q: What is the difference between a "Design Token" and a "Component"? A: A token is a primitive value (color, spacing) based on intent; a component is a functional building block assembled from those tokens. Q: Why should you name tokens based on intent rather than appearance? A: Because it allows for global changes (e.g., changing a brand color) without having to rename every token in the system. Q: What is the "Scale Problem" in UI design? A: The risk of inconsistency and technical debt that arises when designers create unique, one-off screens instead of composing them from a system. Q: When should you refactor a design into a component? A: As soon as you find yourself designing the same pattern or element for a second time. Q: What is "Documentation as an Interface"? A: The idea that documentation is the primary way other team members interact with your system; it must be easy to navigate and always accurate.

Fidelity note

I have high confidence in the core concepts of this summary, specifically the distinction between Tokens vs. Components, the Refactoring workflow, and the Intent-based naming convention. These are the pillars of Wathan and Schoger's argument. I am slightly less certain on specific minor anecdotes (like specific "button" evolutions) as these can vary depending on which version of their portfolio/case studies is being referenced, but the methodology remains consistent.