How to Read Specs
Authority, lifecycle, relations, and a practical reading path for the Proto UI catalog
The Specifications section is the public reading guide to Proto UI’s machine-governed entity catalog. It helps you answer “what does the project currently guarantee?”, trace a rule to evidence, and distinguish a stable contract from work that is only cataloged as current direction.
The catalog is intentionally incomplete. Presence does not imply stability, and absence does not imply that an implementation has no behavior.
Authority
Section titled “Authority”When sources disagree, use this order:
- An applicable entity in
spec/**is authoritative. - Internal contract prose can fill an uncataloged gap, but cannot override an entity.
- Engineering records preserve observations, alternatives, and time-bound direction; they are not normative.
- Implementation and tests show current behavior. A mismatch with an entity is drift to investigate, not an implicit contract change.
- This website and package READMEs are reader-facing projections and should be corrected when they drift.
The pages in this section explain the catalog; they do not create a second source of truth. Use the entity ID and criterion ID when a review or implementation needs an exact, stable reference.
Entity types
Section titled “Entity types”| Prefix | Entity | Responsibility |
|---|---|---|
C- | Contract | Cross-cutting protocol rules and acceptance criteria |
P- | Prototype | Official prototype or prototype-part identity and behavior |
M- | Module | Semantic module identity and the contracts it satisfies |
A- | Adapter | Official Adapter profile, target runtime, and reviewed support decisions |
D- | Decision | Stabilized design or governance choice |
HC- | Host capability | Capability expected from or projected to a host |
T- | Test | Conformance case and executable evidence mapping |
V- | Version | Release identity, channel, package policy, and publication evidence |
K- | Knowledge | Shared vocabulary and explanatory model |
Entities form a typed graph. Relations such as satisfies, verifies, supports, provides, and omits connect a rule to ownership and evidence. For Adapter profiles specifically, a module missing from both supports and omits is uncataloged—not implicitly supported or unsupported.
Lifecycle is separate from release version
Section titled “Lifecycle is separate from release version”Every entity has a since version and a lifecycle status. since records when the identity entered catalog/version history; it does not claim that draft semantics were already stable. For an ordinary non-Version entity, activeSince records the release version at which explicit semantic admission made the guarantee stably applicable; it may equal since when the identity is introduced already stable. Version entities continue to use their separate publication-evidence lifecycle rather than activeSince.
| Status | Meaning |
|---|---|
active | Current applicable guarantee |
draft | Cataloged current direction, not a stable public guarantee |
deprecated | Kept for compatibility or migration; read deprecatedSince and replacedBy |
removed | Historical and unavailable from removedSince onward |
Availability and stable applicability are therefore different queries. An ordinary entity can be present from since while not becoming a stable guarantee until activeSince, and its current active status must not be projected backward across that boundary. Legacy active entities without durable activation provenance may omit activeSince and remain auditable instead of receiving invented history.
Do not collapse three different things into one “current version”:
V-PROTO-UI-0008records the published, immutable 0.2.0 stable ecosystem snapshot.- The checked-out catalog is the current workspace projection and may include later draft work.
- At the time of this page,
V-PROTO-UI-0009describes a draft 0.3.0-alpha.0 release train; it is not publication evidence.
A package being published in 0.2.0 does not automatically make every related entity active. Read the entity lifecycle and the release evidence independently.
A practical reading path
Section titled “A practical reading path”Start with Core for the portable boundary and authoring phases. Then follow the capability that owns your question:
- Lifecycle, Template, and Props
- Event, Expose, and State
- Context, Anatomy, and Feedback
- asHook and Rule
For an exact claim, continue from the named entity to its criteria, relations, sources, and T-* evidence. For motivation, return to the Whitepaper. For implementation mechanics, continue to Engineering or Reference.