Development Contract

Type: Proposal
Status: Active candidate v0.1
Canonical for: The proposed Development Contract requirements within this candidate architecture
Depends on: Package interpretation rule and upstream research; normative language is internal to this proposal

Purpose

The Development Contract binds a governed design concept to a real implementation. It states how the component is imported, configured, executed, constrained, tested and versioned.

It cannot establish selection intent merely by exposing props. It must link every governed API choice back to the relevant Design Contract concept.

1. Implementation identity

Each implementation MUST declare:

Information	Level
shared `conceptId`	MUST
framework/platform	MUST
package and export	MUST
canonical import	MUST
source location	MUST
implementation version/range	MUST
status and deprecation	MUST
Storybook/example location	SHOULD
Figma/Code Connect mapping	CONDITIONAL

The agent must not infer an import or component’s existence from training knowledge when an authoritative current binding is available.

2. API contract

Every public property MUST expose:

programmatic name;
type;
required/optional status;
default;
description;
semantic dimension or implementationOnly designation;
allowed values;
semantic concept mapped to each governed value;
version introduced/deprecated;
platform differences;
interaction with other properties when relevant.

For callbacks and events, the contract MUST describe payload, timing, cancellation and side effects.

An enum declaration prevents invented values only when enforced. Each value still needs an explicit semantic mapping when it affects a design decision.

3. Behavior contract

The Development Contract MUST describe or link executable evidence for:

rendered semantic element or platform role;
action/navigation/submission behavior;
event ordering;
controlled and uncontrolled behavior where supported;
loading and asynchronous behavior;
disabled/read-only behavior;
focus behavior;
error behavior;
state transitions;
server/client or runtime limitations;
side effects and external dependencies.

Where behavior is inherited from a native element, the contract SHOULD state the element and any deviations.

4. Composition API

The contract MUST identify:

accepted children, slots or subcomponents;
required children;
cardinality;
nesting restrictions;
context providers or parent requirements;
incompatible child/prop combinations;
layout ownership boundaries;
portal/layer behavior where relevant.

Constraints SHOULD be represented in the strongest authoritative form already available: types, runtime checks, schemas, tests or explicit rules. The contract does not require one universal constraint language.

5. Constraint records

Each rule that can invalidate an implementation SHOULD have a stable rule record:

Field	Meaning
`ruleId`	Stable reference used by docs, validation and tests.
`scope`	Component, property, composition, platform or runtime context.
`condition`	Observable trigger.
`requirement`	Required, prohibited or cardinality outcome.
`rationale`	Why the rule exists.
`severity`	Error, warning or advisory.
`enforcement`	Type, schema, runtime, lint, test, review or not enforced.
`repair`	Action the agent can take after failure.
`source`	Authoritative design/accessibility/product rule.
`exceptions`	Named and scoped exceptions.

Deterministic validators MUST distinguish structural failure from semantic-selection failure.

6. Token and asset bindings

The Development Contract MUST identify:

token package/source;
token type;
semantic token references used by the component;
state/theme/context mappings;
allowed overrides and extension points;
prohibited raw values or internal selectors when governed;
icon and asset imports when they cannot be inferred safely.

Generated inventories MAY derive this information from source, but derived records must retain commit/version provenance.

7. Accessibility implementation

The contract MUST link the Design Contract’s accessibility requirements to implementation evidence:

semantic element/role;
accessible-name implementation;
ARIA properties and relationships;
keyboard handlers;
focus-management code;
announcement behavior;
automated accessibility tests;
manual keyboard/screen-reader test status where available;
known gaps and unsupported states.

Passing an automated accessibility test does not prove every composition is accessible. Coverage must be explicit.

8. Examples and executable states

The Development Contract SHOULD expose:

minimal import/use example;
examples for every governed property value;
significant interaction and state examples;
local composition examples;
invalid examples linked to validation errors where safe;
Storybook/portable stories or equivalent executable fixtures.

Examples are evidence of known configurations, not an exhaustive grammar.

9. Testing and validation

The contract MUST identify which checks exist and what they prove:

Check	Possible claim
Type/build test	API shape and import compile.
Unit test	Local behavior.
Interaction test	Known user flow and state transitions.
Accessibility test	Tested automated/manual requirements for named states.
Visual regression	Appearance of known states.
Mapping validation	Figma/code connection integrity.
Contract validation	Required fields, links, mappings and rule references.
Semantic agent evaluation	Correct selection/configuration under a defined task set.

The first six do not establish semantic agent correctness. Agent evaluation results belong to an AI-optimisation record linked to the contract version.

10. Lifecycle and change contract

Every breaking or semantic change MUST state:

affected concept, property, value or rule;
previous and new meaning;
implementation version;
design-library version;
migration path;
alias/compatibility behavior;
documentation and example updates;
test and mapping updates;
whether agent evaluations are invalidated and must be rerun.

Renaming without semantic change and semantic change without renaming must be recorded differently.