Shared contract kernel
Type: Proposal
Status: Active candidate v0.1
Canonical for: Shared identity, lifecycle, provenance, linkage and conflict-handling fields in this candidate architecture
Depends on: Package interpretation rule and upstream research; normative language is internal to this proposal
The kernel connects the Design and Development Contracts without forcing them into one source file or serialization format.
1. Canonical identity
| Field | Level | Meaning |
|---|---|---|
conceptId | MUST | Stable, system-owned identifier that does not change when a display label or API spelling changes. |
conceptType | MUST | Component, subcomponent, pattern, composition, token or other governed concept type. |
preferredLabel | MUST | Current human-facing name. |
aliases | SHOULD | Search terms, historical labels and alternate surface names. |
description | MUST | Concise definition of what the concept is, not only how it looks. |
owner | MUST | Team or role accountable for semantic and implementation accuracy. |
The canonical identifier is not expected to communicate meaning by itself. Names remain important signals, but identity must survive renaming.
2. Lifecycle and scope
| Field | Level | Meaning |
|---|---|---|
contractVersion | MUST | Version of the logical component contract represented by the linked Design and Development Contracts. |
systemVersion | MUST | Design-system release or version range to which the contract applies. |
status | MUST | Proposed, experimental, preview, stable, deprecated or removed. |
introducedIn | SHOULD | First supported system/package version. |
deprecatedIn | CONDITIONAL | Version where deprecation began. |
replacedBy | CONDITIONAL | Canonical concept replacing the deprecated concept. |
supportedPlatforms | MUST | Design and implementation platforms covered by the contract. |
productScope | SHOULD | Global, platform, product or domain-specific scope. |
3. Source authority and provenance
Every linked artifact MUST declare:
| Field | Meaning |
|---|---|
artifactType | Design guidance, Figma component, TypeScript API, source, Storybook, token source, test, accessibility guidance or evaluation. |
uri | Stable artifact locator. |
authority | Whether this artifact is authoritative for identity, semantics, API, visual realization, behavior or verification. |
version | Commit, release, file version or retrieval timestamp. |
provenanceMode | Authored, derived, asserted or evaluated. |
lastVerified | Time the link and asserted relationship were checked. |
No single artifact must own every fact. Exactly one source SHOULD be authoritative for each governed fact. When two artifacts are intentionally co-authoritative, the synchronization rule MUST be explicit.
4. Contract linkage
The kernel MUST link:
- one Design Contract;
- at least one Development Contract for each supported implementation;
- Figma/design-library identity when one exists;
- documentation and examples;
- tests and validators;
- token or variable sources where applicable.
Mappings MUST be directional and explicit. A shared name is not sufficient proof that two artifacts represent the same concept.
5. Semantic mapping records
When different layers use different labels, use an explicit mapping record:
| Field | Meaning |
|---|---|
semanticConcept | Stable concept being represented. |
designProperty / designValue | Figma or design-tool spelling. |
codeProperty / codeValue | Implementation spelling. |
documentationLabel | Human documentation term. |
mappingStatus | Exact, contextual, deprecated or unsupported. |
conditions | Platform, theme, parent, state or version conditions. |
This allows a public API to retain a historical value while its governed meaning is made explicit. It does not assume aliases improve agent accuracy; that remains an evaluation question.
6. Conflict handling
Contract validation MUST report:
- missing authoritative source;
- broken artifact links;
- Figma/code value mismatch;
- documented value absent from the implementation;
- implementation value without a documented meaning;
- conflicting defaults;
- lifecycle/version disagreement;
- rules referencing removed concepts;
- examples that violate current constraints.
Conflicts MUST remain visible until resolved. Retrieval tooling must not select one silently based on source order.