What is a design contract?
A shared agreement about how a product gets built and how its design decisions survive the next change.
You agree on a button. A few weeks later, the product has several versions of it. One has a different radius. Another uses a hardcoded color. A third was rebuilt for a new screen because someone couldn't find the original.
Each change may look reasonable on its own. Together, they start to undo the decisions the team already made. The cost shows up in repeated reviews, extra implementation work, and a product that feels less coherent with every release.
This is the problem we use a design contract to address.
"Contract" describes a working agreement between the people and tools building the product. It gives those decisions a form that designers can review, engineers can implement, and coding agents can read.
Why we use a design contract
A design decision can live in a mockup, a component library, a stylesheet, a chat, or someone's memory. When those sources disagree, the next person has to interpret which one matters. Often, they make another local decision just to keep moving.
We want the agreed decisions to be available where implementation happens. A contract names what the team has accepted and makes departures visible while there is still time to discuss them.
That matters when people write the code. It matters just as much when an agent writes it. A request to "match our style" leaves a lot open to interpretation. A named token, an approved button, and a clear review path give the implementer something concrete to follow.
A design, a design system, and a design contract do different jobs
These ideas work together. The distinction is the question each one helps the team answer.
- A design: what should this experience be?
- A design works through a particular problem: the user's task, the flow, the hierarchy, the layout, and the interactions. It helps the team decide what to build and how it should feel in context.
- A design system: what can we build with?
- A design system provides reusable foundations, components, patterns, and guidance. Tokens give shared values meaningful names; components turn repeated interface decisions into reusable building blocks.
- A design contract: what have we agreed the implementation will follow?
- The contract identifies the approved choices, the rules for using them, and how to handle a departure. Paired with checks, it helps the team see whether new code follows that agreement.
A design system can already include governance, checks, and contribution rules. In that case, a contract makes part of that existing agreement explicit and readable by tools. It can sit within the system rather than becoming a separate source to maintain.
For context, the GOV.UK Design System pairs components with usage guidance and coded examples. The Design Tokens Community Group's format specification describes how named design decisions can be shared across tools. We build on those ideas by making the team's approved choices available to the implementation workflow.
What goes into the agreement
A useful contract is specific enough to guide the next change. For the parts of an interface it covers, it should identify:
- The approved tokens. Which names represent the colors, typography, spacing, and radii the implementation should reference.
- The approved components. Which button or input to use, how to select its appearance, and which sizes and states belong to that design.
- The usage rules. Where a choice belongs and which changes require a conversation with the team.
- The change process. Who reviews a departure, whether it is an exception or a reusable pattern, and how the agreement gets updated.
- The checks. Which departures tools can detect and which questions still need human review.
The contract can start with a small set of decisions the team already relies on. Its value comes from being clear, current, and used during implementation.
One button, one shared decision
Imagine a new settings page needs a save action. The design shows a primary button. The system provides the button and its tokens. The contract tells the engineer or agent to use that approved implementation, including its existing states.
- Reuse the approved button. Select its documented appearance and reference the shared tokens instead of recreating the styling.
- Check the change. If the new code introduces a local radius or overrides a state, a check can flag that departure from the agreement.
- Resolve the departure. Return to the approved design, or bring the new requirement to the team for review.
- Record the decision. If the team adopts a new reusable pattern, update the agreement deliberately so future work can use it.
A token alone doesn't capture that whole decision. Referencing
var(--primary-base) may select an approved color, while the rest of the
button still differs from the approved component. The agreement covers both the
ingredients and the component the team chose.
This also gives experimentation a path. A new requirement can lead to a new design; review decides whether it belongs in the shared system.
What it gives the people building the product
For the designer: decisions that carry into implementation
The designer can make the intended foundations and component choices explicit, then see where implementation departs from them. That creates room to spend review time on the experience, hierarchy, and new requirements instead of repeatedly rediscovering the same styling differences.
It also makes feedback more actionable. "Use the approved input and preserve its focus state" gives the engineer a concrete next step.
For the engineer: clear choices and useful feedback
The engineer gets a smaller set of implementation questions to resolve from scratch. They can find the accepted tokens and components, understand what a check is reporting, and know where to take a requirement the current system doesn't cover.
When they use a coding agent, the same agreement can guide the agent's work. The engineer still reviews the result, with a shared reference for the design decisions it should preserve.
For the team: shared memory and deliberate change
The team gains a record that survives a handoff, a new hire, or a switch in tools. People can see which decisions are established and which are open for discussion.
Over time, the goal is to spend less effort reconciling accidental differences and more effort improving the product together. A contract helps by making a deviation a visible decision the team can resolve.
How we use it in Grum
In our workflow, Grum makes the repository's reviewed tokens, approved components, and usage rules available to a coding agent before it changes the UI. The agent uses that contract as its implementation reference, then checks the source for drift before finishing.
When a requirement falls outside the agreement, there is a review path. An approved exception covers that departure; adopting a new shared pattern is a separate decision. Keeping those decisions explicit helps the agreement stay useful.
A source check has a specific scope. It can identify covered departures in code; it does not establish that a live page looks right or that an experience works well. We still need visual review, accessibility testing, and product judgment.
That is why we use a design contract: it carries the decisions we have already made into the next implementation, so the team can give its attention to the decisions that still need to be made.
Request early access