An open source design system that's fully customizable and agent ready
TypeScript
docs: require dependable public API contracts (#5726)
Cindy Zhang13ac93d5c3c6
diff --git a/docs/specs/AST-002/spec.md b/docs/specs/AST-002/spec.mdindex 367d85ac2b..1a704edfee 100644--- a/docs/specs/AST-002/spec.md+++ b/docs/specs/AST-002/spec.md@@ -22,6 +22,8 @@ affects_consumer_docs: []Keep Astryx public APIs intentional. A prop should represent a distinction thecaller owns, not expose a choice the component can make correctly by itself.+That need is only the first gate. The proposed API must also have clear meaning,+dependable behavior, and promises the component can keep.Every public prop becomes a permanent concept that consumers, documentation,tests, themes, migrations, and reviewers must understand. The burden is to show@@ -38,6 +40,12 @@ immediate example.## Requirements+A new prop is admitted only when it passes both gates:++1. **Need:** the caller owns information the component cannot derive.+2. **Contract:** the API clearly describes a dependable result the component can+ enforce.+- **FR1 — A prop represents caller-owned intent.** A new public prop is justifiedonly when two otherwise identical situations require different resolved designoutcomes and the caller owns which outcome applies.@@ -58,6 +66,22 @@ immediate example.- **FR6 — High-level components have a higher threshold.** Opinionatedcompositions prefer internal resolution and composition over accumulatinglow-level tuning props.+- **FR7 — The public concept is understandable.** Its name and values describe+ caller intent without requiring consumers to know the rendering technique that+ implements it.+- **FR8 — The result is predictable.** Each value has a stable, observable effect+ that consumers can explain and tests can verify. A data attribute, theme hook,+ or implementation difference alone is not a public outcome.+- **FR9 — The API can keep its stated promise.** The API shape carries or owns+ the information needed to produce the claimed result. Documentation and review+ arguments do not credit an enum or styling switch with accessibility,+ association, or validation behavior it cannot perform. The contract depends+ only on props, owned children, owned context, and platform facts the component+ can verify.+- **FR10 — Every supported state is independently correct.** Accessibility,+ behavior, and required visual communication do not become valid only when an+ unverified external condition is assumed. Solve the base component problem+ before adding API to select between incomplete solutions.### Platform support@@ -70,28 +94,37 @@ immediate example.## Current-state impact-- API review guidance must add the FR5 admission argument before new props are- accepted.+- API review guidance must require both the caller-need argument and the+ dependable-contract argument before new props are accepted.- Before this rule is used as an automated or routine blocking gate, a blindedhistorical benchmark must measure both correct pauses and false blocks. Apattern of pausing clearly justified APIs means the rule needs refinement.-- Component-spec public concepts should record caller ownership and why the- distinction is not derivable.+- Component-spec public concepts should record caller ownership, why the+ distinction is not derivable, the observable result, and how the component can+ keep the promise.- Existing props are not removed automatically. They are evaluated when touched,when an adjacent prop is proposed, or when they cause a concrete maintenance orconsistency problem.-- The proposed PowerSearch editor-popover maximum width is the motivating case:- its width is an internal resolved design choice rather than a caller-owned- distinction, so a new public tuning prop does not meet this rule.+- The proposed PowerSearch editor-popover maximum width is the motivating case+ for the need gate: its width is an internal resolved design choice rather than+ a caller-owned distinction, so a new public tuning prop does not pass.+- The proposed ProgressBar `presentation` prop is the motivating case for the+ contract gate. External visible text is caller-owned context, so the need is+ real. But the enum only switches rendering. It carries no value or relationship+ and cannot verify or improve the external content. It therefore cannot support+ the accessibility claim used to justify it. Its endpoint marker also does not+ solve the base contrast problem.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| -------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |-| FR1, FR5 | Blinded historical API review benchmark | recent utility, mid-range, and composition API additions | Reviewer accepts a prop without identifying caller-owned semantic variation |-| FR2, FR3 | Component tests and real-browser layout evidence | content, container, viewport, parent context, and platform variation | Public API exposes a value the component can derive reliably |-| FR4, FR6 | API surface review for utility, mid-range, and composition components | existing slot, theme, style, layout, and behavior seams | High-level component accumulates one-off tuning props instead of using its owning layer |-| Burden | Benchmark classification: allow, correct pause, false block, not applicable | recent accepted and rejected API changes | Clearly justified APIs are repeatedly paused or blocked without surfacing a real decision |+| Contract | Verification | Representative states | Mutation or failure expectation |+| --------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |+| FR1, FR5 | Blinded historical API review benchmark | recent utility, mid-range, and composition API additions | Reviewer accepts a prop without identifying caller-owned semantic variation |+| FR2, FR3 | Component tests and real-browser layout evidence | content, container, viewport, parent context, and platform variation | Public API exposes a value the component can derive reliably |+| FR4, FR6 | API surface review for utility, mid-range, and composition components | existing slot, theme, style, layout, and behavior seams | High-level component accumulates one-off tuning props instead of using its owning layer |+| FR7, FR8 | Consumer examples and behavior tests | default, each public value, composed use, and unsupported use | Meaning depends on implementation knowledge or tests assert only classes/data attributes |+| FR9, FR10 | Component ownership and accessibility review | owned content, external sibling content, missing or incorrect context | A state is correct only when the caller fulfills a promise the component cannot verify |+| Burden | Benchmark classification: allow, correct pause, false block, not applicable | recent accepted and rejected API changes | Clearly justified APIs are repeatedly paused or blocked without surfacing a real decision |## Decision log@@ -109,6 +142,21 @@ Rejected: adding props whenever a consumer asks for a different internal layoutvalue. That approach duplicates design decisions across callsites and expands thepermanent API without adding semantic information.+### DEC-2 — Caller need does not admit an unclear or unenforceable API++**Reference:** `spec:AST-002/DEC-2`+**Decider:** `cixzhang`, `2026-08-30`++A non-derivable caller distinction passes only the need gate. The proposed prop+must also name an understandable concept, produce a dependable observable result,+and use a mechanism capable of fulfilling the promise used to justify it.++Rejected: `ProgressBar presentation`, because its enum only switches rendering.+It does not carry, associate, verify, or improve the external visible value used+in its accessibility argument. Its endpoint marker also does not solve the base+contrast problem. Solve the component behavior first; reconsider API only if two+independently correct presentations remain.+## Open questionsNone.