Overview
The design system had documentation. That wasn't the problem.
Epic's design system had been growing for years. Components were designed, built, and shipped. Guidance existed. But designers were reading from one place, while engineers were reading from another.
Teams had learned to work around the gap. The documentation wasn't wrong. It just wasn't unified. If design and engineering aren't reading the same thing, they're not building the same thing.
Epic Games
2024 - 2026
Process
The instinct was to fix the content. The real fix was the architecture.
The temptation in situations like this is to write more. More guidance, more detail, more examples. But more content in two separate places is still two separate places. The problem wasn't what the documentation said. It was where it lived and who it belonged to.
A structured workshop was run with cross-functional stakeholders, surfacing what design needed, what engineering needed, and what the system would need to become over time. Requirements were mapped across content, structure, features, and long-term constraints. The output was a formal tool-comparison matrix that evaluated out-of-the-box documentation platforms against a custom-built reference site across various criteria. The matrix made the decision easier.
One destination, one voice.
Building a custom reference site meant more than consolidating two destinations into one. It meant the system could finally speak with a single voice to both designers and engineers, with usage guidance, API props, component behavior, and onboarding living together rather than in parallel.
It also meant the system could demonstrate itself.
The reference site was built using the Epic Design System's own components, so documentation wasn't a description of the system. It was an instance of it. Every page was proof that the system worked.
Outcome
Documentation problems are almost always architecture problems.
The question is never just what to write. It's where it lives, who it belongs to, and whether its structure can hold up as the system grows.
Built for humans. Ready for machines.
The content standards and consistency built into the reference site turned out to matter in ways that weren't fully anticipated at the time. When AI-assisted workflows became a real initiative, the documentation was already structured with consistent intent, constraints, rules, and behaviors, the kind of machine-readable foundation that most teams have to retrofit.
That foundation made it possible to package documentation as an LLM file, integrate it into Claude Code, and build a queryable custom GPT for conversational access to system guidance. The documentation had been built for humans. It turned out to be ready for machines, too.