Design Contract
Type: Proposal
Status: Active candidate v0.1
Canonical for: The proposed Design Contract requirements within this candidate architecture
Depends on: Package interpretation rule and upstream research; normative language is internal to this proposal
Purpose
The Design Contract states the governed design decision: what the component is for, how it differs from alternatives, what its properties mean, how it behaves from the user’s perspective and which compositions remain coherent and accessible.
It is not a Figma inventory, visual specification or prose usage page by itself. Those artifacts may be authoritative sources linked from the contract.
1. Identity and ownership
The Design Contract MUST reference the shared conceptId, lifecycle and owner. It MUST identify the design-library component or pattern when one exists and state whether the design asset is authoritative, illustrative or derived.
2. Purpose and selection boundary
| Information | Level | Requirement |
|---|---|---|
| Purpose | MUST | State the user-facing job. Where the system uses a role taxonomy, name the applicable interaction/function category without treating it as product intent. |
| Supported intent | MUST | Name the tasks or outcomes the component can support. |
useWhen | MUST | Give observable conditions that justify selection. |
avoidWhen | MUST | Give observable conditions that disqualify selection. |
| Closest alternatives | MUST | Name plausible alternatives and the deciding distinction. |
| No-match behavior | SHOULD | State when the system has no suitable component or product guidance is required. |
| Product exceptions | CONDITIONAL | Identify product-owned departures from the shared rule. |
Weak descriptions such as “a flexible component” or “use appropriately” do not satisfy this section.
3. Semantic property model
Every property that changes a governed design decision MUST declare:
| Information | Level |
|---|---|
| property identifier and display label | MUST |
| semantic dimension | MUST |
| definition | MUST |
| allowed values | MUST when finite |
| definition of every governed value | MUST |
| default and what the default means | CONDITIONAL |
| whether meaning is absolute or relative | MUST |
| required scope for relative values | CONDITIONAL |
| independent or coupled dimensions | MUST |
| known conflicts or dependencies | CONDITIONAL |
Provisional semantic dimensions include an interaction/function category, user/product intent, hierarchy, emphasis, appearance, consequence/impact, status/tone/severity, context and state. The role-category terminology is intentionally unresolved pending later taxonomy work. The contract MUST not treat these categories as interchangeable. It MAY use different categories when the system’s evidence supports them.
A generic public property such as variant is permitted. Its contract entry must still identify the dimension each value represents and disclose mixed dimensions where they exist.
4. User-observable behavior and state
The Design Contract MUST describe:
- the action or outcome triggered;
- whether the component performs an action, navigation, selection, disclosure or another provisional interaction/function category;
- user-visible states and their meanings;
- entry and exit conditions for significant states;
- loading, disabled, error, selected or expanded behavior when supported;
- what remains editable, reversible or recoverable;
- asynchronous progress and completion behavior when supported.
State must remain distinct from enduring component intent unless the system explicitly governs them together.
5. Composition and relationships
The Design Contract MUST identify local composition requirements when they exist:
- allowed and required parents;
- allowed, required and prohibited children;
- named slots/regions and their purpose;
- required peers;
- cardinality such as exactly one or at most one;
- incompatible components or property combinations;
- target/control relationships;
- related patterns and when they supersede the component;
- scope of relative hierarchy.
Broad product composition MAY remain in a pattern or product contract. If so, the component contract MUST link to it rather than duplicate it.
6. Accessibility contract
The Design Contract MUST state the intended native or accessibility-platform role and accessible name requirement. It MUST link or specify:
- keyboard interaction;
- focus entry, movement and restoration;
- required labels, descriptions and relationships;
- screen-reader/state announcements;
- non-color communication;
- contrast, reflow and reduced-motion requirements where relevant;
- known limitations or unsupported compositions.
Where native platform semantics fully define behavior, the contract SHOULD reference them rather than restating an incomplete substitute.
7. Content contract
The Design Contract SHOULD define:
- required content fields;
- label construction and verb guidance;
- ambiguous or prohibited terminology;
- length or truncation behavior when governed;
- error, loading and empty-state language;
- localisation and grammatical constraints;
- content examples and counterexamples.
Content is part of component meaning when an agent relies on the label to infer intent.
8. Visual and token realization
The Design Contract MUST link governed visual properties to semantic tokens or variables when those tokens exist. It SHOULD distinguish:
- semantic token role;
- concrete value/theme realization;
- state-specific token changes;
- context such as inverse/on-dark;
- responsive and density behavior;
- appearance versus selection intent.
Raw color or scale names may remain implementation details. They must not be the sole representation of a governed semantic distinction.
9. Examples and decision evidence
The Design Contract MUST provide at least:
- one canonical use example;
- one close alternative comparison;
- one non-example for a likely misuse;
- one example for each conditional composition rule that is otherwise difficult to understand.
Examples MUST link to the contract version and MUST NOT silently contradict current constraints.
10. Open context
The Design Contract MUST distinguish:
- system-governed facts;
- facts derivable from the canonical implementation;
- product/domain context required at decision time;
- unresolved or intentionally flexible judgment.
An agent should be able to determine when the Design Contract is insufficient rather than invent a product rule.
Design Contract completion gate
A Design Contract is complete for selection and composition only when:
- purpose and boundaries distinguish the component from plausible alternatives;
- every governed property/value has an explicit dimension and meaning;
- relative semantics name their scope;
- significant states and user-observable behavior are defined;
- local composition and accessibility requirements are explicit or linked;
- examples and non-examples agree with the rules;
- product-owned uncertainty is identified.