Skip to content

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.md
index 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 the
caller 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 justified
only when two otherwise identical situations require different resolved design
outcomes and the caller owns which outcome applies.
@@ -58,6 +66,22 @@ immediate example.
- **FR6 — High-level components have a higher threshold.** Opinionated
compositions prefer internal resolution and composition over accumulating
low-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 blinded
historical benchmark must measure both correct pauses and false blocks. A
pattern 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 or
consistency 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 layout
value. That approach duplicates design decisions across callsites and expands the
permanent 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 questions
None.