Frame
There was a component library. There was no system.
An inherited library held most of the product's components; the rest were scattered across working files. Variants belonging to the same component lived in different files than their parents. Page organization mixed atomic levels and functions arbitrarily. There was no documentation beyond a few dev-handoff annotations, no contribution process, and no shared logic for how any of it fit together.
A design system is only as real as its structure and documentation. Without them, you have a pile of parts in active use, slowly decaying. That was the inherited library; I was brought in to make it a system.
The Problem
The inherited library had three structural absences, and they compounded.
No documentation. No reference layer at all. Designers had no place to check how a component was meant to be used; engineers had no source of truth for states, specs, or behavior. Every usage question was answered by asking a person or guessing.
No coherent structure. Components were grouped into buckets like "Elements," "Components," and "Content" — categories that mixed atomic levels and functions with no consistent logic. Overlays, action bars, and sliders all lived on an "Elements" page. A "Components" page held menus, labels, and assorted CTAs. Nothing had a predictable address. Finding a component meant knowing where someone had happened to put it.
No governance. No contribution model, intake process, versioning discipline, or onboarding. Components got added wherever was convenient; variants drifted into working files and never came back. The library couldn't take on new work in an orderly way, which is why the scatter kept growing.
Underneath all three: teams were actively using the library while it sat in this state. This couldn't be a greenfield rebuild done in isolation and swapped in.
The Approach
The system had to be replaced piece by piece, and nothing could be carried over on faith. An inherited system encodes arbitrary past decisions, and the only defensible way to replace them was to re-derive each choice from evidence. Every category ran the same evidence-driven cycle (industry research and comparative analysis against systems like Material, Carbon, Fluent, and Atlassian, then audit, consolidation, rebuild, documentation, and governance), applied per sprint rather than as one upfront pass.
The hardest calls were about restraint. Coming off building the Cast design system at Google, I'd worked alongside the Material team and knew its highly flexible component model and semantic token structure well. My first instinct was to port that sophistication wholesale. The overreach showed up first in component configuration. The instinct to consolidate: collapse similar components into shared, flexible variant sets, proved unfitting. Many DIRECTV components were highly specialized and tied to specific product features. The system needed specificity, not customization. Two content cards that are always used in two distinct media carousels and have different layout and property needs did not belong in the same variant set; merging them would make accurate properties configuration long and tedious, exactly where selection errors enter. So consolidation became a usage-driven judgment call: merge where components genuinely overlapped, keep them separate where feature-specificity made a shared set a liability.
The same overreach showed up in token and style semantics. Material's paired color roles earn their complexity when components sit on many backgrounds and carry many surfaces; DIRECTV's didn't, and porting the full apparatus produced ambiguity instead of clarity. The semantic instinct is to call a field "second line of text" so it scales, but when that line is always marketing copy on a card that only appears in one component, naming the prop "marketing copy" leaves no room for guessing.
The structural rebuild was the foundation everything else sat on. The move was to replace the inherited buckets with a taxonomy where a component's place was determined by what it was and what it did, so its location followed from the structure itself.
The rebuild also had to stay invisible to the people relying on it: nothing could break a live instance. That meant a strict building-and-migration discipline — a consistent standard for how components were built, with a migration method that preserved component connectivity as they moved into the new library.
Then came the missing layer: documentation, the structured reference that turns a component file into a system teams can actually learn and use.
