Skip to content

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.md
index 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 proxy
may 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 or
pen can reach each supported interaction. Hover is never the only discovery or
activation 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 focus
indicator 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 focus
returns 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 |