An interface contract should describe the state, not just the style
“Build a polished search panel” leaves the hard decisions hidden. What appears before a query? What remains while results load? What happens when nothing matches, the request fails, or a keyboard user clears the query? A palette and screenshot cannot answer those questions.
An interface contract turns the request into reviewable behavior before implementation. It does not need to prescribe a framework or pretend that every state has been tested. It needs stable state names, observable transitions, content rules, and evidence expectations.
A fictional remote search, four different outputs
Consider a hand-authored component called Remote source search. Its fictional service has 12 records, but the browser does not hold the complete set: submitting a query starts a remote read. No service, model, design skill, component workshop, or application was run for this example.
Loading
loadingSearching the remote source collection…
The previous confirmed results may remain visible, but are not labeled as this query's response.
Ready
ready12 fictional sources available. Enter a query to start a remote read.
Initial state; no request is represented as having run.
No results
no-resultsNo sources match this query.
A real Clear action would restore the initial ready state and focus the search field.
Request error
request-errorThe remote read failed. The query and last confirmed results are preserved.
A real Retry action would repeat only the current read.
These are static semantic illustrations, not screenshots or working controls. They make four implementation obligations visible without pretending a request occurred.
One filled transition record
| From | Event | To | Preserved input | Required behavior | Evidence status |
|---|---|---|---|---|---|
ready | Submit query graph | loading | Query and current results | Mark the read in progress without presenting old results as the new answer. | Proposed |
loading | Submit query graph memory before the first response returns | loading | New query | Abort the older request when possible; in every case ignore its stale response if it arrives later. | Proposed |
loading | Current response contains zero records | no-results | Current query | Offer Clear; Clear returns to the initial ready state and focuses the search field. | Proposed |
loading | Current request fails | request-error | Current query and last confirmed results | Explain the failed read and offer Retry; do not erase confirmed results or label them as the failed query's response. | Proposed |
Five parts of a useful contract
- Purpose: name the user task in one sentence.
- States: give each applicable state a stable ID and say what is visible.
- Transitions: identify the event, resulting state, preserved input, and recovery path.
- Constraints: record semantics, keyboard and focus behavior, responsive rules, reduced motion, content limits, and approved tokens without inventing missing values.
- Acceptance evidence: state what must be observed, at which viewport or environment, and what artifact records the check.
Keep decision status separate from verification. “Approved copy” is not “tested interaction.” A story or specimen can isolate a component state, but its existence does not prove keyboard behavior, live-region announcements, network recovery, or production integration.
What current primary sources establish
Anthropic’s frontend-design guidance describes reusable design guidance as context loaded for relevant tasks and emphasizes deliberate typography, color, motion, and backgrounds. That supports treating aesthetic direction as explicit input; it does not establish that generated output satisfies a product contract.
Storybook’s official story documentation describes stories as captured rendered states of a UI component, expressed through a component and its arguments. That supports using named states as review surfaces. It does not make a story an accessibility, integration, or production test by itself.
The official shadcn Improve repository describes an audit-to-plan workflow. It is relevant only as an example of separating analysis from implementation; this article does not install it, reproduce its skill, or claim its plans are correct.
Use the blank contract before implementation
The companion template leaves all project-specific decisions and evidence fields blank. Fill only the states that apply, explain exclusions, and do not mark a check passed until its evidence exists.
Download the blank interface-contract template
The Source search example, state table, five-part contract, and template are original teaching material. No named tool was installed or run, and no generated interface, accessibility result, productivity result, or personal adoption is claimed.