Candidate Design and Development Contracts v0.1
Type: Proposal
Status: Active candidate
Canonical for: Navigation, interpretation rules and source-of-truth policy for the candidate contract package
Depends on: Current research synthesis, canonical terminology, and semantic-naming reconciliation
This is not an industry standard, empirically proven optimum or AI-optimised result.
These specifications translate the research into a testable operating model.
Global interpretation rule: Normative language inside this candidate architecture is normative within the proposal. It is not proof that the field, a standard or LLM evidence empirically requires this exact architecture, field set or threshold. Every file in this directory inherits this rule.
The package uses the shared canonical research terminology. In particular, a component contract is logical and may connect facts that remain authoritative in different artifacts.
Contract set
- Shared contract kernel: canonical identity, lifecycle, provenance and cross-artifact linkage.
- Design Contract: why a component exists, when it is selected, what it means, how it composes and what experience rules govern it.
- Development Contract: how the component is implemented, configured, constrained, tested and versioned, including the metadata an external access layer can retrieve.
- Worked Button example: an illustrative mapping across the contracts without proposing PDS names or APIs.
- Research traceability: evidence class and source for each contract concern.
- AI-optimisation record: evaluation overlay kept separate from the candidate acceptance profile.
- Practical walkthrough: plain-language explanation of
useWhen,avoidWhen, file placement, agent retrieval and an end-to-end Button example.
What the contracts are trying to solve
Current component truth is distributed:
- design guidance usually carries purpose, use conditions and visual intent;
- Figma carries component identity, properties, variants, tokens and local composition;
- code and TypeScript carry legal APIs and runtime behavior;
- Storybook carries examples, prop metadata and executable states;
- accessibility documentation and tests carry interaction requirements;
- agent skills and MCP services carry retrieval and operational rules.
The contracts do not replace those sources. They link them through stable identity and require the governed facts needed for a decision to be explicit somewhere authoritative.
Normative language
- MUST: required by the candidate v0.1 acceptance profile for the stated capability.
- SHOULD: expected unless there is a documented reason it does not apply.
- MAY: useful in particular domains or implementations.
- CONDITIONAL: required when the component supports the stated behavior or relationship.
These are requirements within this candidate architecture, not claims that public research has empirically proven every field improves LLM performance.
Evidence boundary
The requirements combine four evidence classes:
- Empirical adjacent evidence: names, descriptions, schema wording, retrieval and validation affect related tool/schema tasks.
- Standards precedent: ARIA, DTCG, SKOS, MCP and JSON Schema separate roles, states, labels, types, annotations and constraints.
- Mature-system practice: Carbon, Storybook, Figma, Atlassian, Microsoft and SAP expose different parts of the contract.
- Architecture hypotheses: cross-component semantics, retrieval projections and minimum sufficient packets still need direct evaluation.
The evidence basis and limitations are documented in AI-ready component-contract research and research-bundle reconciliation.
Source-of-truth rule
The contract is an index of governed facts, not automatically a second copy of every artifact.
Each field MUST be one of:
- authored: maintained directly in the contract or its authoritative linked source;
- derived: generated from an authoritative artifact such as TypeScript, Figma or Storybook;
- asserted: documented by an owning team but not mechanically derived;
- evaluated: produced by a named test or agent evaluation.
Every derived or asserted field MUST record its source and version. Conflicting sources MUST fail validation or be surfaced as unresolved; they must not be silently merged.
Exposure and readiness are capability-specific
A component is AI-exposed for a stated access path when an agent can reliably discover, retrieve and inspect its current governed design or implementation artifacts. It may still require the agent to infer selection meaning, usage rules, relationships, constraints or decision logic.
The candidate contracts assume an access path that can make their governed facts AI-exposed. A component can satisfy that lower condition without satisfying this package’s candidate acceptance profile for selection, configuration, composition or another capability.
A component may be ready for implementation but not for selection or composition.
| Capability | Minimum evidence chain |
|---|---|
| Discover | canonical identity, lifecycle and availability |
| Select | purpose, use/avoid boundaries, alternatives and context |
| Configure | property dimensions, value meanings, defaults and constraints |
| Compose | parent/child/peer relationships, slots, cardinality and contextual rules |
| Implement | package/import/API, behavior, tokens and framework binding |
| Verify | deterministic checks, examples/tests and source/version linkage |
The v0.1 baseline does not claim a component is AI-optimised. Optimisation requires model-based evaluation against a specific contract version, retrieval setup, task set and harness.
Retrieval principle
The complete contract is not automatically the model prompt. Agent tooling SHOULD project a decision-specific packet containing:
- the current intent and scope;
- the candidate component and closest alternatives;
- the properties relevant to the current decision;
- applicable use/avoid and composition rules;
- authoritative implementation binding;
- version and provenance;
- validation feedback when a proposed result fails.
This projection is a hypothesis to evaluate. It reflects evidence that excessive, stale or irrelevant context can interfere with selection.
For a concrete explanation of how the pieces could live beside component code and reach an agent, see the practical walkthrough.