Overview
A user interface is built by an end user, a UX designer, a front-end developer, a product owner, a domain expert, a quality engineer and an accessibility specialist. It goes wrong in the gaps between them: between the research and the story, between the mockup and the component, between what was agreed in a review and what actually shipped.
Closing those gaps takes two moves, and this hub is organised around them.
Establish the contracts. Settle, once and away from any particular feature, what the interface is made of. The design system is the visual contract; the core component library is the technical one, and it is the thing user-interface code is actually written against.
Connect the people, and bring the contracts with them. Put UI and UX inside the sessions where the team already decides what to build — story mapping and example mapping — with the established contracts in the room as inputs.
That second word is the load-bearing one, so it is worth stating flatly.
The contracts are inputs, not outputs
Section titled “The contracts are inputs, not outputs”
The sessions do not invent the interface. They decide what to build, knowing what the interface is already made of.
A team that treats the design system as something a feature produces rebuilds it per feature, slightly differently each time. A team that treats it as something a feature consumes gets three things the first team never does:
Estimates that mean something. When the pieces already exist, “two days” is a statement about composition rather than a guess about how long it takes to invent a date picker.
Sessions that close questions instead of opening them. In example mapping, “what happens when the list is empty” is usually answered by the system already has an empty state, and it looks like this — ten seconds, not a design task.
A smaller surface of things anyone still has to get right. Most screen-level decisions were taken upstream and are not re-litigated per screen.
The contracts do change — but by change request, as the exception. When a session finds something genuinely not covered, that is a proposal against an established contract, reviewed by the people who own it, and it lands upstream where every other feature inherits it. It is not a local invention inside one story.
The two attitudes
Section titled “The two attitudes”Both are dispositions rather than activities. You can tell whether a team holds one by watching what happens when it is inconvenient.
| Attitude | The claim | The test of whether you hold it |
|---|---|---|
| User-first | The person who has to use the thing is a first-class input, at inception and while it is being built. | Can a user need send a story back, the way a cost estimate can? |
| Contract-first | Every boundary — including the one between design and code — is written down, agreed, and checkable before it is implemented. | Does something fail when the contract is breached, or does someone just notice later? |
A third follows from the first two rather than standing beside them: journey-first — when both contracts hold, the visual is largely settled, and the remaining risk is whether a person can get through. That is where the testing effort belongs.
What follows for testing
Section titled “What follows for testing”Given both contracts, testing the visual matters less than testing the user journey. That is not a licence to skip visual checking — it is a claim about where the remaining risk actually is.
| What | What it can tell you | What it cannot |
|---|---|---|
| The two contracts | This button is the button, in every state, with the right contrast and the right keyboard behaviour | Whether anyone can complete a task with it |
| Interaction tests | This component behaves as specified, in isolation, with an address when it fails | Whether it is the right component here |
| Visual regression | Something changed that nobody meant to change | Whether the change is wrong |
| Journey tests | A person can get from intent to outcome, through the real screens | Whether anyone does |
| Usability testing | Whether a real person, who did not build this, actually gets through | Anything statistical, or whether they want it |
A screenshot diff is a change detector, not a correctness oracle: it can only tell you that pixels moved, and someone still has to decide whether that was intended. Once components are under contract, most of what a large screenshot suite reports is intended change — which is exactly how such suites become noise and then get ignored.
The last two rows are the pair worth holding together. A journey test keeps the path passable so that a usability session is spent on comprehension rather than on bugs; a usability session finds the thing no assertion was ever going to be written for. Journey-first makes the full argument, including where it does not apply.
How this hub is organised
Section titled “How this hub is organised”| Section | What it holds |
|---|---|
| The process | One feature, from a user need to a shipped interface, with who is in the room at each step |
| Attitudes | User-first, contract-first, journey-first — the three dispositions everything else assumes |
| Contracts | The established design system and core component library, the tokens between them, and how they are kept aligned |
| Practices | The sessions: journey mapping, story mapping, example mapping, four amigos, design critique |
| Testing | What to test at which level, and the budget argument between them |
| Tools | Figma, Storybook, Playwright and axe — what each one enforces |
| MCP | What a model can do here, and where a human still decides |
Contracts are listed before practices on purpose: they are what the practices run against.
The portal itself fronts the two contracts as running artefacts: the design system and the component library.
The honest caveat
Section titled “The honest caveat”Every claim on this site depends on enforcement. A design system nobody generates from, a component library that has diverged from production, and a journey suite that is skipped because it is flaky are all common, and all three are worse than not having them — they carry the maintenance cost and the appearance of rigour without the property that made them worth adopting.
Before adopting any of it, decide what fails the build when the contract is breached. If the answer is nothing, you are buying pictures.
And if the contracts do not exist yet, this hub describes a destination rather than your Monday. Establishing them is a piece of work in its own right, done once and amortised across every feature after it — not something to be attempted inside a story. Until then, expect the sessions to be slower and the estimates to be worse, and be honest about which of the two situations you are in.
This hub is the interface half of a larger argument; the development practices it plugs into live in dev-hub, and the two are meant to be read together.