A design working agreement: propose, and do not ship

This document sits at the root of a design project and tells an agent where its work stops. It needs a folder, not a repository.

Tokens live at: {{tokens_path}} Accessibility floor: {{accessibility_standard}} Shipping means: {{ships_via}}

The division

In code, done is frequently verifiable — the tests pass or they do not. In design, done is a judgement, and it is the judgement people most want to have made themselves.

So an agent may do everything up to that point, and the line is unusually clean: propose, prototype, audit, argue, produce five variants. Do not decide which one, and do not ship.

Safe without asking

• Proposing alternatives, several at a time, with the trade-offs stated.
• Auditing the interface against {{tokens_path}} and reporting every drift.
• Computing contrast ratios and reporting the figures.
• Producing variants for side-by-side comparison.
• Arguing against the brief. An agent that quietly executes a brief it believes is wrong is less useful than one that says so first. Disagreement is wanted; acting on it alone is not.

Stop and ask first

• Shipping anything a user will see, per {{ships_via}}.
• Changing a decision that is already settled. Name which one and why it should be reopened.
• Introducing a value that is not in {{tokens_path}}. A one-off hex is a proposal, not a decision.
• Trading contrast for appearance. See below — this is a floor, not a preference.
• Adding an external asset. A web font, an icon set, a CDN script. These arrive dressed as typographic choices and are privacy and performance decisions: a font host sees every visitor, and a blocking request delays first paint for everyone.

Taste or structure? Establish this before touching anything

The most expensive mistake available here, and it is invited by the language briefs are written in.

“It feels cluttered.” “Can it be calmer?” “Something’s off.” Every one of those is ambiguous between a surface problem and a structural one, and an agent will reach for the surface, because that is what the words point at. Palette, type, spacing. The surface fix usually works — for about a week — and it hides the real problem while looking like progress.

The test, before changing a single value:

Name what the reader is trying to do, and count how many things are in their way.

If the count is high, no palette will fix it, and changing the palette will make the count harder to see.

The Handover — this library — went through exactly this. The first design pass reached for warmth and a serif typeface. The actual difficulty was twelve navigation items and an undifferentiated list of every document on the front page. Restyling produced something that felt better and was not, and the second pass had to undo the styling before it could fix the organisation. The note in the stylesheet still reads: structure first; the surface should be nearly invisible.

What was rejected, and why

This is design’s equivalent of a research dead end, and it is harder, because a research dead end failed. A rejected design frequently worked. It was good and it was not right, and nothing in the artefact records the difference.

Without that record an agent re-proposes it every session, in good faith, because from where it sits the idea is new and obviously reasonable. The cost lands on whoever has to recognise it and explain again.

So each rejection is written down with three things:

• what was proposed
• why it was rejected — the constraint, not the feeling, wherever a constraint exists
• what would change the answer

That third line is what stops the record becoming a wall of no.

Accessibility is a floor

{{accessibility_standard}}, and it is not traded against appearance. The full commitment, what is verified and where to stop lives in the accessibility rootnote — it is stated once there rather than three times across this set.

Two rules that do not follow by default: never trade a passing contrast ratio for appearance, and never write a ratio you did not compute — a figure in a comment is untested and probably unexamined.

Consistency beats local improvement

A component that is better in isolation and different from its siblings has made the system worse. The value of a design system is that it is a system, and an agent optimising one screen at a time will degrade it while improving every screen it touches.

If a change is genuinely right, it is right for the whole set — which makes it a proposal about the system, not an edit to a page.

Reporting honestly

• Separate audits (here is what the system says, here is what the code does) from proposals (here is what I think should change).
• If something was changed because it looked better to you, say that in those words. It is a legitimate reason and a bad thing to disguise as a principle.
• When reporting a contrast figure, say it was computed and from which pair.

Where this lives

A folder, next to the work — with the rejections file, which is the part that gets lost.

One thing to do by hand: without version control nothing records when this document last changed. Write the date on it when you revise it. A working agreement that has quietly stopped describing how anyone works is worse than none, because it is still being followed.