Every UX Decision, Traced to Its Evidence: Building the UX Encyclopedia

Somewhere along the way, design advice on the internet turned into a game of telephone. A study gets quoted, then requoted, then rounded off, and eventually a number nobody can trace becomes a law everybody repeats. I got tired of it. So I built the antidote: a reference library where every single claim has a receipt.

It is called the UX Encyclopedia, it lives at ux.detroit3d.com, and this is the story of how it came together.

What it actually is

The UX Encyclopedia is a free reference for anyone building interfaces: more than one hundred dense pages across ten sections, covering everything from usability heuristics and color contrast to checkout flows, voice interfaces, car dashboards, and even robots. There is a full flows encyclopedia mapping the routes users actually travel, a style encyclopedia that walks through decades of art movements and interface eras, and a section on designing experiences in physical spaces.

The pages are deliberately short and dense. Instead of one giant scroll, the library works like a good colleague: describe your situation and it hands you the two or three pages that answer it. Completeness comes from coverage and routing, not from length.

The one rule I refused to break

Real sources only. Every content page ends with a Sources section, and every citation points at something that actually exists: the original paper, the standard, the documentation. No invented statistics, no mystery URLs, no “studies show” without the study.

Verifying everything turned out to be half the fun, because the received wisdom kept falling apart under inspection. A famous usability book is routinely dated a year late. A beloved psychology effect had been credited to the wrong researchers for years. A major regulation everyone cites as settled law had actually been vacated in court. Where research has replication problems, the library says so right on the page. Conventions are labeled as conventions, vendor claims as vendor claims, and emerging practice as exactly that: emerging.

That honesty is the whole point. Advice you can trace is advice you can trust.

A site that practices what it preaches

A UX reference has no business being a bad user experience, so the website holds itself to the same standards it documents.

I wrote the static site generator from scratch in Node, with no framework and only two runtime dependencies. It reads the markdown library and produces the entire site: navigation, breadcrumbs, a client side search index, structured data for search engines, a sitemap, print styles, and a service worker that makes the whole encyclopedia work offline as an installable app.

My favorite feature is invisible: the build fails on purpose if any color pairing in the design system drops below WCAG AA contrast. Accessibility is not a checklist item that someone remembers to test later. It is a compile error. The site literally cannot ship an inaccessible color pair.

The rest of the design follows the library’s own advice. Body text is set in Atkinson Hyperlegible, a typeface designed by the Braille Institute for maximum legibility. Spacing sits on a consistent eight point rhythm. There are light and dark themes, both contrast checked. Everything works with a keyboard, respects reduced motion settings, and holds together on a phone down to very small screens.

The Situation Finder

Most documentation search assumes you already know the right vocabulary. But designers rarely arrive with the perfect keyword; they arrive with a problem. “My checkout is losing people.” “Does this dark mode have enough contrast?” “How long can a driver safely glance at a screen?”

So the signature feature of the site is a search box that asks “What are you designing?” It indexes not just the full text of the library but a routing table of real situations, and situation matches rank above everything else. Type “checkout” and the top results are not pages that merely mention the word; they are routes to the exact references for forms, checkout flows, and the mistakes that cause abandonment.

Demos you can poke

Reading about Fitts’s Law is fine. Feeling it is better. Dozens of pages carry interactive figures built in plain JavaScript: a playground where you resize and move a target and watch the difficulty index update as you try to click it, a live contrast checker, a demo showing how a decoy price changes what people choose, and a slider that lets you feel the exact moment scattered dots snap into groups.

The style encyclopedia goes further. One demo takes a single card component and reskins it across eight art movements, from Bauhaus to Memphis, and another walks the same card through six eras of interface design. Every skin passes contrast checks. The lesson writes itself: the skin changes, the skeleton does not.

Quality control, the boring superpower

There are no traditional tests in this project, but there is discipline. Every batch of changes gets screenshotted by an automated browser in both themes and at phone width, then checked for zero console errors and zero horizontal overflow. Diagrams get eyeballed at real sizes because a label that overflows its box is a bug, no matter what the code says.

That routine caught everything from figures landing at the bottom of the wrong page to a text replacement bug where a dollar sign in content could silently corrupt a page. Screenshots do not lie, which is more than I can say for my assumptions.

Why I built it

Because good UX advice should not be locked behind paywalls, buried in papers, or mangled by repetition. Whether you are a developer shipping your first settings page, a founder wondering why signups stall, or a designer defending a decision in a meeting, you deserve an answer you can trace to its evidence.

The UX Encyclopedia is my attempt to hand you that answer in under a minute. It is free, it works offline, and every claim on it can be checked. Go describe your situation at ux.detroit3d.com and see where it routes you.