An open source design system that's fully customizable and agent ready
TypeScript
spec(interaction-modality): wrapper focus rings come from one shared owner module (#9183)
Cindy Zhang932cfb963c6a
diff --git a/docs/architecture/interaction-modality.md b/docs/architecture/interaction-modality.mdindex 75ac0502b9..a0cd3ffc85 100644--- a/docs/architecture/interaction-modality.md+++ b/docs/architecture/interaction-modality.md@@ -13,6 +13,7 @@ applies_to:[packages/core/src/utils/interactionModality.ts,packages/core/src/utils/focusOutline.stylex.ts,+ packages/core/src/privateAttributes/focusOwner.stylex.ts,packages/core/src/hooks/useFocusReturnVisibility.ts,packages/core/src/hooks/useIndicatorFocusRing.tsx,packages/core/src/Layer/useTouchTrigger.ts,@@ -114,7 +115,16 @@ work.element that paints on its behalf.- **INV3 — One focus move has one owning indicator.** A wrapper or visual proxymay paint for the semantic owner, but sibling controls paint their own focus- and replacement content cannot silently remove the owner's indicator.+ and replacement content cannot silently remove the owner's indicator. A Core+ wrapper that paints the ring for one primary control among other tab stops+ takes the one shared focus-owner style and owner attribute from+ `privateAttributes/focusOwner.stylex.ts`, so the wrapper rings only while that control+ has keyboard focus, and a nested owner or a sibling control rings itself;+ no component writes the attribute or its selector itself. Implementation+ gap: the module does not exist yet, and Item, Token, the clickable and+ selectable cards, Thumbnail, the Selectors, SideNavItem, and ChatComposer's+ body write their own ring conditions. Swizzle does not yet carry an+ unexported owner module into an ejected copy.- **INV4 — Every modality has an operable path.** Keyboard, pointer, and touch orpen can reach each supported interaction. Hover is never the only discovery oractivation path. A tooltip's scrolling overflow is the one exception, as@@ -251,6 +261,9 @@ is asked to carry a new decision.modality.- `utils/focusOutline.stylex.ts` and focus tokens — provide the shared focusindicator mechanics and theme seam without choosing component ownership.+- `privateAttributes/focusOwner.stylex.ts` — owns the private focus-owner attribute, its+ selector, and the one shared wrapper ring for INV3's primary-control owners;+ it is not exported from the package.- `hooks/useFocusReturnVisibility.ts` — applies last-input visibility when focusreturns from adaptive surfaces.- `hooks/useIndicatorFocusRing.tsx` — lets the semantic owner guarantee paint on@@ -287,7 +300,7 @@ reachability, newer-intent precedence, and the evidence/scope guard were approve| Invariant | Evidence | Failure signal || ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || INV1, INV2 | Programmatic-focus cases after keyboard and pointer input in representative component tests | Programmatic focus invents a modality, or pointer history paints the keyboard indicator |-| INV3 | Direct-owner, wrapper-owner, replaceable-indicator, and nested-action cases | No indicator, two indicators, or replacement content can opt out |+| INV3 | Direct-owner, wrapper-owner, replaceable-indicator, and nested-action cases, including a Token inside an Item and a control inside a card; evidence gap for the shared-module cases: the module does not exist yet | No indicator, two indicators, replacement content that can opt out, or a component that writes the focus-owner attribute or selector itself || INV4 | Keyboard, mouse, touch, and pen browser paths where applicable | Hover-only behavior, sticky touch hover, or unreachable action || INV5 | Disabled, busy, and read-only DOM and activation assertions | Inactive control reacts, eligible control loses focus, or state changes with modality || INV6 | Public API review and representative source inspection | A component adds caller-controlled modality without a separate API decision |