Centralizing documentation for the Epic Design System

When knowledge lives in two places, it effectively lives in neither.

The Epic Design System had been growing for years. Components were designed, built, and shipped. Guidance existed. But designers were reading from one place, and engineers were reading from another.

When knowledge lives in two places, it effectively lives in neither. That was the problem I kept coming back to.

The Epic Design System reference site

The fix wasn't more content

The temptation is to write more. But more content in two separate places is still two separate places. I knew early on that the problem wasn't what the documentation said — it was where it lived and who it belonged to.

I ran a structured workshop with cross-functional stakeholders to surface what design needed, what engineering needed, and what the system would need over time. From that, I built a tool-comparison matrix evaluating documentation platforms against a custom-built reference site. Out-of-the-box platforms covered most current requirements. None of them could scale with the system.

Workshop output organized into themes — Content, Structure, and Features — each mapping to a section of the reference site

Tool comparison matrix: Notion, Zeroheight, and a custom site

I recommended custom. It meant more work, but it also meant we could build the reference site using the design system's own components. The documentation wouldn't be a description of the system. It would be proof that the system worked.

The architecture

I mapped every section, every audience path, and every content type. That decision mattered.

The sitemap covered separate onboarding paths for designers and engineers, contribution guidelines, component documentation, and a full guidelines library spanning accessibility, color, icons, layout, and typography.

Epic Design System sitemap

One destination, one voice

I structured usage guidance as a decision rather than a description. The reasoning behind each rule lived alongside the rule itself. I wanted a designer and an engineer to read the same page and reach the same answer — without having to cross-reference anything.

That meant writing for the moment someone needs to make a call, not for the moment they're browsing. There's a difference, and it shapes every sentence.

Alignment guidance structured as a decision table — left vs. right, mapped to when each applies

Button pairing rules are presented as a visual matrix of valid combinations. A designer and an engineer read the same table and reach the same answer

An instance of the system

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.

Component overview page

A unified reference site

The question I always come back to 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.

The unified reference site became the place both designers and engineers used — usage guidance, technical implementation, API props, and onboarding in a single destination. Teams began requesting pattern documentation and full accessibility guidance. When people ask for more from a knowledge system, it means it's working.

Epic Design System landing page