Skip to content

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

TypeScript

docs: define interaction modality architecture (#5734)

Cindy Zhang457de8dc91ec
diff --git a/docs/architecture/interaction-modality.md b/docs/architecture/interaction-modality.md
new file mode 100644
index 0000000000..8eb73d1b14
--- /dev/null
+++ b/docs/architecture/interaction-modality.md
@@ -0,0 +1,166 @@
+---
+schema_version: 1
+template_version: 1
+kind: architecture
+id: architecture:interaction-modality
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-08-30
+owners: [cixzhang]
+applies_to:
+ [
+ packages/core/src/utils/interactionModality.ts,
+ packages/core/src/utils/focusOutline.stylex.ts,
+ packages/core/src/hooks/useFocusReturnVisibility.ts,
+ packages/core/src/hooks/useIndicatorFocusRing.tsx,
+ packages/core/src/Layer/useTouchTrigger.ts,
+ packages/core/src/,
+ ]
+verified_by:
+ [
+ packages/core/src/CheckboxInput/CheckboxInput.test.tsx,
+ packages/core/src/DropdownMenu/DropdownMenu.test.tsx,
+ packages/core/src/Selector/Selector.test.tsx,
+ packages/core/src/Slider/Slider.test.tsx,
+ ]
+deciding_specs: []
+---
+
+# Interaction modality architecture
+
+## Purpose
+
+Astryx components behave predictably when people move between keyboard, pointer,
+touch, pen, and programmatic focus. This record defines the shared modality
+state, the boundary between modality and component focus ownership, and the
+evidence required when either changes.
+
+It does not define focus-ring appearance, hover paint, press treatment, or new
+component APIs. Those remain with Design Conventions, theme tokens, and the
+owning component family.
+
+## System model
+
+Astryx tracks the last input modality as one shared state:
+
+- a key press without Meta, Alt, or Control held sets `keyboard`;
+- a pointer press, including mouse, touch, or pen, sets `pointer`;
+- a key press with Meta, Alt, or Control held does not change modality; and
+- before any input, the state is `keyboard` so initial or restored focus remains
+ perceivable.
+
+Programmatic focus does not create a new modality. Its focus indicator follows
+the last input modality: it is hidden after pointer input and shown after
+keyboard input. Components use the browser's `:focus-visible` behavior together
+with the shared modality state where `:focus-visible` alone cannot distinguish
+the initiating input.
+
+Modality answers **whether the shared focus indicator should be visible**.
+Component ownership answers **which element paints it**. The semantic focus
+owner may paint on itself, delegate paint to an owning wrapper, or paint on a
+visual proxy when the focusable element is intentionally hidden. That ownership
+does not change the modality state.
+
+Hover capability is separate from modality history. Hover behavior is available
+only to hover-capable pointers and remains an enhancement over keyboard, click,
+and touch paths. Touch and pen presses participate in pointer modality even when
+a family gives them different gesture behavior.
+
+Disabled, busy, and read-only semantics are also separate from modality. Their
+existing API and accessibility contracts decide whether focus and activation are
+available; modality only controls the focus indicator on an eligible focus
+owner.
+
+## Boundaries and invariants
+
+- **INV1 — Last input owns programmatic focus visibility.** Programmatic focus
+ preserves the current modality. After pointer input it does not show the shared
+ focus indicator; after keyboard input it does.
+- **INV2 — Modality and focus ownership stay separate.** Shared modality decides
+ visibility. Each component family decides the semantic focus owner and the
+ 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.
+- **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.
+- **INV5 — Existing state semantics win.** Disabled controls do not become
+ interactive because of modality. Read-only and busy controls preserve their
+ documented focus and activation behavior.
+- **INV6 — Modality remains internal.** Components derive modality from shared
+ browser input state. A public focus-visibility or modality prop requires a
+ separate public-API decision.
+
+## Allowed variation
+
+Component families keep their shipped interaction models:
+
+- actions may paint the shared outline on the focusable action;
+- bordered fields may paint their established field-focus treatment on an owning
+ wrapper;
+- hidden native inputs may have owner code paint on the visible indicator;
+- menus may move focus with mouse hover so pointer and keyboard share one
+ highlighted item; and
+- spatial controls may move focus during a pointer gesture without showing the
+ keyboard focus indicator.
+
+These are ownership and behavior choices, not alternate modality definitions.
+A new visual representation still requires design review; this record does not
+authorize one.
+
+## Change coupling
+
+- A change to modality tracking, focus-return visibility, shared focus styles, or
+ visual-proxy ownership updates the relevant representative tests in the same
+ pull request.
+- Moving a component's semantic focus owner or paint owner verifies keyboard
+ order, programmatic focus after both modalities, one-indicator ownership, and
+ disabled, busy, and read-only behavior where applicable.
+- Adding pointer-dependent behavior verifies mouse, touch, and pen as applicable,
+ including a non-hover path.
+- Changing focus appearance remains coupled to Design Conventions and theme
+ verification. Exposing modality through public API remains coupled to
+ `architecture:public-component-api`.
+
+## Owning code
+
+- `utils/interactionModality.ts` — records and exposes the shared last-input
+ modality.
+- `utils/focusOutline.stylex.ts` and focus tokens — provide the shared focus
+ indicator mechanics and theme seam without choosing component ownership.
+- `hooks/useFocusReturnVisibility.ts` — applies last-input visibility when focus
+ returns from adaptive surfaces.
+- `hooks/useIndicatorFocusRing.tsx` — lets the semantic owner guarantee paint on
+ a replaceable visual indicator.
+- Component and family implementations — own focus destination, keyboard model,
+ pointer and touch behavior, and any wrapper or proxy that paints the indicator.
+
+## Deciding specs
+
+No separate specification changes this record. The last-input rule was approved
+as a system architecture decision by `cixzhang` on 2026-08-30.
+
+## Verification
+
+| 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 |
+| 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 |
+
+Real-browser evidence is required when the behavior depends on
+`:focus-visible`, pointer capability, touch or pen synthesis, or rendered focus
+ownership. Unit tests prove event routing and DOM state but do not replace that
+evidence.
+
+[PR #5648](https://github.com/facebook/astryx/pull/5648) is a verification
+benchmark for the record, not an authority for it. Its ChatComposer fixture
+covers keyboard-owned editor focus, pointer suppression, clearing an existing
+keyboard indicator on pointer press, and keeping internal action focus owned by
+the action. The benchmark also verifies programmatic editor focus after both
+keyboard and pointer input before the behavior is treated as complete.