Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

spec(AST-089): style the public ref element, otherwise the outermost root (#7931)

Xinzi Zhou2fbf3249f627
diff --git a/docs/specs/AST-089-styling-target/spec.md b/docs/specs/AST-089-styling-target/spec.md
new file mode 100644
index 0000000000..d39fec886c
--- /dev/null
+++ b/docs/specs/AST-089-styling-target/spec.md
@@ -0,0 +1,253 @@
+---
+schema_version: 4
+template_version: 2
+kind: system-spec
+id: spec:AST-089
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+phase: proposed
+owners: [cixzhang, imdreamrunner]
+affects_architecture: [architecture:public-component-api]
+affects_families: [family:layout-primitives, family:input-fields]
+affects_contributing: [contributing:api-conventions]
+affects_consumer_docs: [principles]
+---
+
+# Ref-first DOM styling target
+
+## Intent
+
+A consumer uses `style`, `className`, and `xstyle` on the same element they can
+reach through the component's public DOM ref. When the component exposes no
+unprefixed ref, those props style its unique outermost DOM element.
+
+Named part styling and explicitly recorded compatibility exemptions retain their
+own targets. Ref identity, not the presence of a caller-supplied ref value,
+defines the default styling target.
+
+## Non-goals
+
+- Require every component to accept general styling props or expose a DOM ref.
+- Add, move, or select among public ref targets to change styling behavior.
+- Change styling precedence, semantic props, events, accessibility, or ref behavior.
+- Replace named part styling or the input family's prohibition on root styling.
+- Specify enforcement algorithms, registries, or CI topology.
+
+## Requirements
+
+- **FR1 — Public DOM ref first.** A stable Core web component that accepts any of
+ `style`, `className`, or `xstyle` and exposes an unprefixed DOM `ref` MUST apply
+ every accepted general styling prop to the element promised by that ref's
+ public contract on every supported render path, except for the explicit
+ compatibility exemptions below. The target MAY be an inner control or a sole
+ detached surface; DOM ancestry does not override a valid public ref target.
+- **FR2 — The API selects the target, not the callsite.** FR1 applies whether the
+ caller passes `ref`, omits it, uses a callback or object ref, or passes `null`.
+ A transient `ref.current === null`, a closed surface, or an unmounted target
+ MUST NOT cause styling to move to another element. When the promised target is
+ absent, there is no element to style until it renders. Internal refs and named
+ refs such as `contentRef`, `triggerRef`, or `controlRef` do not select the
+ default; they retain their separately named part contracts.
+- **FR3 — No exposed ref means outermost fallback.** Only a component whose public
+ API exposes no unprefixed ref uses the unique outermost component-owned DOM
+ element. It has no component-owned DOM ancestor, and whenever any owned DOM
+ renders, there MUST be exactly one owned root across the component's trees.
+ A sole portal root qualifies; hidden measurement peers, composed wrappers,
+ and detached public surfaces count as owned DOM. Consumer-supplied children
+ and external portal hosts do not themselves count as owned roots. When no
+ owned DOM renders, general styling has no effect and does not move to another
+ element. An empty path does not establish a target guarantee for an otherwise
+ headless component. The fallback does not depend on runtime ref presence or value.
+- **FR4 — An unusable ref is not an absent ref.** An unprefixed `ref` that resolves
+ to an imperative handle rather than directly to a DOM element, an ambiguous
+ public ref contract, or an exposed ref that is not forwarded supplies no
+ default styleable element. A DOM-valued member of an imperative handle does
+ not make the handle a DOM ref. Such a component MUST NOT introduce general
+ styling props until it has a valid target contract. It MAY expose explicitly
+ named part styling instead. It MUST NOT silently use the outermost fallback
+ merely because FR1 cannot be satisfied. Existing behavior requires a scoped
+ exemption; ordinary ref-forwarding defects remain defects under their current owners.
+- **FR5 — Composition preserves public identity.** A composed or polymorphic
+ component MUST guarantee that every accepted general styling input reaches its
+ promised public DOM ref element, or its unique outermost root when it exposes
+ no ref. Merely forwarding the props to an unrestricted consumer component does
+ not prove this guarantee. Adding, removing, retyping, or retargeting an exposed
+ ref MUST NOT silently change the styling target.
+- **FR6 — Named parts and family exclusions remain intact.** Part styling uses the
+ complete `<part>Xstyle`, `<part>ClassName`, and `<part>Style` set under
+ `spec:AST-071`. `family:input-fields` FR10 and DEC-7 continue to forbid root
+ styling on Field-composed components and define their `container*` and
+ `control*` targets. Having a native input ref does not restore forbidden root
+ styling, and having a named `controlRef` does not reroute general or named
+ styling. Components bound by `family:input-fields` FR10 are outside this
+ default, including any root styling they still accept until FR10 lands.
+ Semantic props retain their owning contracts' targets.
+- **FR7 — Exemptions preserve a bounded contract.** Each exemption identifies the
+ component, affected render path, retained styling target, actual ref contract
+ or missing guarantee, reason, and owning contract. It exempts only the stated
+ divergence from this default; it does not approve an existing violation of
+ another current owner. Explicitly listed split or missing general-styling
+ targets are legacy enforcement exemptions, not valid replacement contracts:
+ their current preservation/composition obligations remain open. Unrelated ref
+ failures, dropped neutral props, named-part defects, and styling-composition
+ defects outside the listed target scope are not exempt. New components and new
+ divergence paths MUST NOT inherit an exemption by analogy. Removing or
+ expanding an exemption requires an explicit owner decision; there is no
+ automatic expiry or forced migration.
+- **FR8 — Compatibility and authority remain explicit.** A ref API change is also
+ a styling compatibility review when it would change the default target. Moving
+ a released styling or ref target, combining split targets, or removing an
+ accepted prop follows `spec:AST-017`, with the required compatibility decision,
+ migration evidence, consumer documentation, and release classification. Making
+ this record current also updates conflicting current API, family, and component
+ claims together. No exemption waives a migration already required by another
+ current owner.
+
+### Platform support
+
+- Scope: stable Core web components and the composed render paths that implement
+ them. Hooks are not independently governed; a component implemented with a hook
+ still follows the component contract.
+- Non-DOM renderers, providers without a DOM styling surface, and Lab components
+ are outside this rule. A component that accepts no general styling props owes
+ no default styling target.
+- Browser feature support is unchanged. Element/ref-identity tests prove
+ targeting; real-browser evidence is needed for a future migration's observable
+ layout, appearance, or interaction claims, not for this record's text alone.
+
+## Current-state impact
+
+The canonical shared API owner is `architecture:public-component-api`, whose
+INV5 and INV6 preserve styling on the documented contract element and composition,
+and whose INV8 preserves the documented ref target. They do not require styling
+and ref targets to be the same element. `architecture:public-component-api`
+INV15 and `spec:AST-071` FR1 describe part sets as styling for elements other
+than the root, and INV6 and `family:input-fields` FR10 call the unprefixed set
+root styling inputs; FR1's inner-control target amends those claims on
+promotion. These current claims remain authoritative while this record is draft.
+
+The ref-first default applies only to supported general styling inputs without
+an explicit exemption. Existing component-specific surface targets, named parts,
+and family exclusions remain documented rather than silently reclassified.
+
+The input family's [part-target contract](../../families/input-fields.md#cross-component-invariants)
+owns `container*` and `control*` semantics. An exemption here does not waive any
+remaining implementation debt under `family:input-fields` FR10 and DEC-7.
+
+### Compatibility exemptions
+
+These exemptions apply only to the named existing API and render paths. They
+retain the styling and ref targets stated below; supplying, omitting, detaching,
+or clearing a ref does not select another target. All accepted general styling
+inputs continue to compose on the retained element unless a separately listed
+legacy gap remains. A topology difference alone needs no exemption when the
+styling set already reaches a valid public DOM ref element.
+
+#### Target-preservation exemptions
+
+| ID | Component and path | Retained styling target / public ref target | Reason / owning contract |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| E1 | CheckboxInput and Switch, all supported rendered modes | Outer whole-field `div` / native checkbox or switch `input` | Preserve whole-field styling and the correctly exposed semantic-control ref. Neither composes Field or belongs to FR10's excluded root-styling set; shared API and respective control owners. |
+| E2 | CommandPaletteInput | Query wrapper `div` / query `input` | Current `component:CommandPaletteInput` FR3 corroborates the separate visual-wrapper and native-control seams. |
+| E3 | Horizontal Stepper, expanded or compact | Horizontal frame `div` / ordered-list `ol` | Preserve frame styling and list measurement/ref identity; `component:Stepper`. Vertical list-target styling needs no target exemption. |
+| E4 | Timestamp and Timer, supported rendered temporal states | Outer Text `span` / inner `time` | Preserve the existing temporal wrapper rather than moving general styles to `time`. `component:Timer` FR5/ORD2 and temporal component/shared API owners describe the seam; Timer's broader current timer-system wording remains an unresolved authority tension in OQ3. |
+| E5 | ContextMenu and MoreMenu pointer/sheet paths | Inner menu/content `div` / trigger wrapper or trigger button | Existing general styles describe the menu, not its trigger. Shared API and menu owners retain that target; existing sheet ref-forwarding debt is not waived. |
+| E6 | DropdownMenu pointer/sheet; Popover automatic/custom/external-anchor and sheet; HoverCard text/element/fragment-trigger paths | DropdownMenu inner menu `div`, Popover inner painted `div` (the sheet's panel under the sheet presentation, `component:Popover` DEC-8), or HoverCard floating `div` / no unprefixed component ref | There is no unique outermost fallback across trigger, persistent template, host, and surface trees. Named/payload refs are not a component `ref`. `component:Popover` owns painted-surface styling; respective menu/HoverCard and shared API owners retain the other targets. |
+| E7 | PowerSearch when the nested Tokenizer Field box renders; PowerSearch's sheet presentation | Nested Field box through Tokenizer's `container*` inputs / outer PowerSearch wrapper; sheet presentation: the styling set on the field container and `ref` on the root (`component:PowerSearch` DEC-3) | Preserve the higher-level composition's current styling projection. Where the Field box is absent, the part has no effect and warns, never reroutes. `component:PowerSearch`, `component:Tokenizer`, and the input-family part contract; no root styling is added to Tokenizer. `family:input-fields` FR10 binds PowerSearch. |
+| E8 | InputClearButton's generic-tooltip path | Native clear `button`; only accepted `xstyle` / no public component ref | Tooltip peers prevent unique outermost fallback. Shared API owner; missing class/style counterparts and incomplete icon-part inputs remain AST-071 obligations. |
+| E9 | Existing unrestricted custom-root APIs: Stack, HStack, VStack, StackItem, Item; custom link/router branches of Avatar, Button, IconButton, Link, Tab, Token, DropdownMenuItem/ContextMenuItem/BreadcrumbMenuItem, NavHeadingMenuItem, TopNavHeading, TopNavItem, TopNavMegaMenuItem, SideNavHeading, and SideNavItem; custom Icon root handoff and Table wrapper/transform handoff | Existing lowered class/inline-style and ref handoff to the caller component, not a newly selected DOM node; for Table, styling and the public ref remain on the received semantic table, which wrapper/context output may retain, wrap, duplicate, detach, or remove | Exemption from the new composed style/ref-identity proof requirement only. Preserve the released handoff without asserting that arbitrary caller output has a DOM ref or forwards styling. An object handle does not trigger outermost fallback. Native/built-in branches still owe their own identity contract; new APIs and divergence paths are not covered. `family:layout-primitives`, shared API, and each root/transform owner. |
+| E10 | BottomSheetSwitcher, every step | Every step's sheet dialog carries the accepted `className`, `style`, and `xstyle`; the public ref resolves to the host dialog (the active sheet's, else the exiting or resting one) | Each step is its own sheet dialog, so the switcher's dialog surface applies to all of them; styling only the ref dialog would leave the other steps unstyled. `component:BottomSheetSwitcher` owns which dialog hosts the ref. |
+
+#### Legacy default-enforcement exemptions
+
+These are explicit exclusions from the new uniform-target check, not valid
+replacement contracts. Existing current-owner obligations remain open. A failed
+ref binding in the rows below does not authorize runtime outermost fallback.
+
+| ID | Component and path | Existing gap in the ref-first target guarantee | Obligations retained |
+| --- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| L1 | ChatComposer rendered frame/body paths | `style` and `className` reach the frame/public-ref element; `xstyle` reaches the body | Shared API INV5/INV6; no approved split target is inferred from a draft. |
+| L2 | SideNavItem rendered paths | `xstyle` reaches the outer column; `className` and `style` reach the inner primary control/ref binding | Shared API INV5/INV6/INV8; the split and ambiguous root-ref promise remain open. |
+| L3 | TopNav content-bearing drawer paths | All accepted general styling inputs and the public ref are dropped | Shared API INV5/INV6/INV8; truly empty output is not an exemption by itself. |
+| L4 | SideNav content-bearing drawer-content paths | All accepted general styling inputs and the public ref are dropped | Shared API INV5/INV6/INV8; a conditional footer root does not repair the loss. |
+| L5 | TypeaheadItem's nonempty caller `item.element` path | Accepted general styling and public ref are not applied to the returned caller node | Shared API INV5/INV6/INV8; arbitrary caller output is not a guaranteed forwarder. |
+| L6 | SegmentedControlItem | Accepted `className` is overwritten; dynamic StyleX output can overwrite the entire accepted inline `style` | Shared API INV5/INV6; this is lost styling, not a permissible split or precedence decision. |
+| L7 | VisuallyHidden's accepted inherited `xstyle`, intrinsic and custom paths | `xstyle` is ignored (`component:VisuallyHidden` FR3) rather than applied to its ref element; `className` and `style` are not accepted | Shared API/AST-071 obligations and the styling-free intention require reconciliation; the exemption does not create styling support. |
+| L8 | Icon's registry-rendered path; CheckIndicator's checked-glyph path | Icon: its public ref reaches the svg (`component:Icon` FR8), and the styled wrapper is unpromised implementation (AV2); CheckIndicator: styling reaches the rendered span, but the accepted public ref is not forwarded there | Exclusion from the new style/ref-identity proof only. Icon promises no span; CheckIndicator's unforwarded ref is no INV8 waiver. Replacement/custom paths are separately scoped. |
+| L9 | Dialog, AlertDialog, and CommandPalette inline-open paths | General styling reaches the inline `div`; the accepted dialog ref is unbound | Exclusion from the new style/ref-identity proof only. Existing INV8/declared-element debt remains; inline-closed null does not choose another target. |
+| L10 | SideNav target-bearing topbar and drawer paths | Existing general styling reaches the topbar `div` or drawer dialog, but the accepted public ref is unbound | Exclusion from the new style/ref-identity proof only. Existing INV8 obligations remain; no outermost fallback or changed ref target is authorized. |
+
+InputGroup's general styling and actual public ref both reach its inner group
+`div`, but its current Field-composition scope is unresolved under FR10. Matching
+this default does not allow styling that another current owner forbids; OQ2
+requires that owner decision. Declared-ref type mismatches on otherwise
+co-targeted native branches likewise remain independent obligations, not reasons
+to move styling.
+
+Hook renderer styling channels are outside this component-default rule. Their
+own current contracts continue to govern, including any accepted renderer-prop
+gaps. The absence of general styling on Tooltip, Toast, ToastViewport, Theme,
+MediaTheme, SyntaxTheme, and providers is not a grandfather exemption or a
+promise that they have no owned DOM.
+
+### Owner projections
+
+The shared target and exemption boundary belong in
+`architecture:public-component-api` and `contributing:api-conventions`.
+`family:layout-primitives` owns its polymorphic member contracts;
+`family:input-fields` owns its root-styling exclusion and part targets. Each
+exempted component's owning contract and consumer docs distinguish the styling
+and public ref targets on the applicable paths. Current records are not rewritten
+by this draft.
+
+## Verification
+
+| Contract | Verification | Representative states | Mutation or failure expectation |
+| -------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| FR1–FR2 | Distinct inline-style, class-name, and StyleX markers asserted against the public DOM ref element | inner control, detached target, callback/object/omitted/null ref; closed/open surface | Passing or omitting ref changes the styling target; a null ref reroutes styling. |
+| FR3–FR4 | Public-prop/type inspection and owned-root identity tests | no exposed ref and one root; no exposed ref and peer roots; fully empty render, then mount; imperative handle including a DOM-valued member; ambiguous or dropped ref | An unusable ref triggers outermost fallback or a component with no valid target gains general styling props. |
+| FR5 | Element/ref-identity fixtures and compatibility review | intrinsic `as`, guaranteed composed target, unrestricted `as`, added/removed/retargeted ref | Forwarding alone passes as identity proof or a ref API edit silently moves styles. |
+| FR6 | Owning contracts, public types, semantic pass-through tests, and named-part markers | standalone, grouped, and horizontal-label fields; public named part refs | A Field-composed component gains forbidden root styling or a named ref retargets general/part styling. |
+| FR7 | Explicit component/path/style-target/ref-target exemption coverage and negative cases | every retained target and relevant mode; new sibling and new render path | A blanket waiver hides a ref failure or covers an unlisted divergence. |
+| FR8 | Current-record consistency, consumer migration evidence, compatibility review, and release metadata | exemption retention; ref API edit; target move; prop removal | A target changes silently or a draft is treated as authority. |
+
+## Decision log
+
+### DEC-1 — General styling follows the public DOM ref
+
+**Reference:** `spec:AST-089/DEC-1`
+**Proposed decider:** `imdreamrunner`
+
+Consumers can inspect, measure, focus, and style the same publicly addressable
+DOM element. The unprefixed ref contract selects it even when the caller passes
+no ref value. Only an API with no unprefixed ref uses the unique outermost root;
+explicit exemptions preserve established targets.
+
+Rejected: choosing the target from `ref.current` at runtime, because mounting or supplying a ref would move styling.
+Rejected: an outermost default that styles the whole owned root independently of ref identity, because a consumer's ref and styling would then address different elements.
+
+### DEC-2 — Existing divergences are explicit compatibility exemptions
+
+**Reference:** `spec:AST-089/DEC-2`
+**Proposed decider:** `imdreamrunner`
+
+The default does not force a breaking target move, new ref API, or prop removal.
+An exemption preserves only the named existing target and path. Named family
+exclusions and their separately approved migrations retain their own authority.
+
+Rejected: treating every existing divergence as an immediate migration prerequisite, because the default would force unrelated consumer changes.
+
+## Open questions
+
+- **OQ2 — Does the Field-composed root-styling prohibition include InputGroup?**
+ (`human-api`) InputGroup's styling and ref co-target its inner group, but its
+ Field composition and collaborator classification leave current FR10 scope
+ inconsistent. The family and direct API owners reconcile that scope; meeting
+ this default does not waive FR10.
+- **OQ3 — Which current timer claim owns the retained wrapper/ref split?**
+ (`human-api`) `component:Timer` FR5/ORD2 retains Text-wrapper styling and a
+ `time` ref, while `spec:AST-037` has broader root wording. The shared API and
+ timer owners reconcile the current claims; E4 does not invent precedence.