An open source design system that's fully customizable and agent ready
TypeScript
spec(public-component-api): public props use the system's existing vocabulary (#9749)
Cindy Zhange797650e5776
diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.mdindex 9f3991a42f..5d6d8a501f 100644--- a/docs/architecture/public-component-api.md+++ b/docs/architecture/public-component-api.md@@ -107,7 +107,17 @@ guidance owns the process used to propose and test APIs.shared naming grammar. Component-specific vocabulary stays local. A prop thatchooses how a component responds to input is named `<thing>Behavior` and takesa closed union of behavior names, and its name holds no input word (press,- touch, tap, hover, mouse, click) when the values can name the behavior.+ touch, tap, hover, mouse, click) when the values can name the behavior. A+ public prop names a system primitive with the system's existing vocabulary:+ it introduces no new term for a concept the system already names (DEC-1). A+ gap between an element and its anchor is an `offset`, as `useLayer`'s+ `offset` is; a distance a positioned element keeps in from a container's or+ the viewport's edge is an `inset`, as LayerProvider's and ToastViewport's+ `inset` are. Depth is+ `elevation`, which takes values from `Elevation`, as Card, Button, and Banner+ take it. `lift` names motion under a press, such as+ Switch's thumb lift, Slider's `springs.sliderLift`, and ContextMenu's+ `springs.contextMenuLift`, so it does not name a layout distance.- **INV3 — One prop controls one independent concept.** A prop does not silentlysuppress an unrelated prop. A parent does not duplicate state already owned bya composed child. One interaction behavior is one prop, never parallel touch,@@ -311,6 +321,9 @@ source. Lab components are not stable public promises until promotion.defect does not by itself require consumer-doc changes.- A new prop includes the admission argument from `spec:AST-002/DEC-1`; it doesnot get accepted only because it solves one callsite.+- Public-API review rejects a public prop that names an existing system concept+ with a new term (INV2, DEC-1); the prop takes the system's word for that+ concept.- Adding a touch presentation or a touch input mode for an open surface to astable component checks INV16: a `presentation` value keeps the fine-pointersurface and mode, and every such touch mode is reachable by callers.@@ -359,12 +372,27 @@ Transition Action sequencing and pending behavior belong to their component orfamily contract. This record links that owner once it is current; it does notcopy the component matrix.+### DEC-1 — Public props use the system's existing vocabulary++**Decider:** `cixzhang`, `2026-11-03`++A public prop that names a system primitive uses the word the system already+has for it, so a builder who knows one component reads the same concept the+same way on the next. A gap from an anchor is `offset`, a distance a+positioned element keeps in from an edge is `inset`, depth is `elevation`, and+`lift` stays the name of motion under a press. An API for a new component, such as a search field, starts from+the existing patterns in the system and introduces no new term for a concept+the system already names.++Rejected: component-local names for shared concepts.+## Verification| Invariant | Evidence | Failure signal || ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || INV1, INV8 | Export, public-subpath, prop, and ref checks | A promised component/type cannot be imported or its ref cannot reach the contract element || INV2 | Naming and logical-direction lint/tests | Equivalent concepts use conflicting names or physical direction leaks into public API |+| INV2, DEC-1 | Public-API review against the system vocabulary | A public prop names a concept the system already names, such as a distance, depth, or press motion, with a new term, or uses `lift` for a layout distance || INV3, INV4 | Historical API review benchmark and `spec:AST-002` evidence | A prop combines unrelated axes or exposes a derivable implementation choice; a new interaction-behavior prop that is not a `<thing>Behavior` closed union, carries an input word where its values can name the behavior, splits one behavior across per-input props, or, as a new prop, defaults to anything but the shipped behavior || INV5, INV6, INV7 | BaseProps/passthrough lint and representative runtime tests | Consumer ARIA/data/style/events are dropped, clobber component semantics, or fail to compose || INV9 | Published-surface, Changeset, migration, and public-type checks | A released API changes without explicit compatibility evidence |@@ -403,6 +431,10 @@ Known verification gaps:and `useResizable` `collapsible` and CodeBlock `isCollapsible`; Calendar`mode` and FileInput `isMultiple`; FileInput `mode`; Tokenizer andPowerSearch `tokenOverflowBehavior`; OverflowList `behavior`.+- INV2: a shipped prop that names a concept with a word the system uses for+ another keeps its name until a minor renames it under INV9. Outline's+ `offset` is the distance below the top of its scroll root+ (`component:Outline` FR4), not a gap from an anchor.- INV22: known gaps include `useLongPress`, `useMenuPress`,`usePressFeedback`, `useClickableContainer`, `useInputContainer`,`useOverlay`, `useCombobox`, `useMultiCombobox`, `useResizable`,