UX Interaction Patterns

Category: Quality Attributes · Areas: ui, frontend

Description

Areas

ui, frontend

Boundary

Owns basic user-visible behavior independently of framework, component library, brand or hosting. ux-radix and packaged-design-system compose this baseline; neither library adoption nor accessibility-friendly primitives prove a user flow works. a11y-wcag-aa owns compliance; e2e-framework owns the execution harness.

Constraints

Native links and navigation landmarks for destinations; visible current location plus aria-current=“page” where page navigation exists. Same-page tabs use aria-selected and the tab pattern, not aria-current as a substitute.
All interactive flows complete by keyboard with visible focus. Apply composite arrow keys/typeahead only to the actual widget pattern, not ordinary nav links.
Modal dialogs trap focus, have accessible names, support applicable dismissal, and restore focus to their trigger or a logical successor. Non-modal popovers allow focus to leave; do not impose modal trapping on them.
Async actions show progress, prevent duplicate submission while pending, and show success/failure with a recovery path. Preserve entered data on failure.
Forms expose labels and actionable validation errors; placeholders alone are not labels. Data surfaces have applicable loading, empty and error/retry states.
Destructive actions follow the project’s explicit confirmation or recovery contract. Irreversible/high-impact actions require confirmation; reviewed undo may govern low-risk reversible actions. Never silently delete.
Search exposes query, results/no-results and reset. Plain text filtering does not require a combobox; selectable suggestions use the matching widget pattern.

When to use

Interactive user interfaces. Static content, pure APIs and source-free prose record non-applicability rather than inventing interaction flows. Patterns apply only to affected surfaces. Existing ux-radix selections inherit this baseline; select it directly with other libraries, without selecting Radix as a side effect.

Artifact Impact

USER_STORIES: applicable UX behaviors as stable observable acceptance criteria
DESIGN_SYSTEM: app-specific navigation, state, modality and recovery conventions
TEST_PLAN: UX Coverage in affected STPs, mapping patterns and AC IDs to assertions
IMPLEMENTATION_PLAN: interaction results linked through existing STP mappings per workflows/concerns/verification/practices.md

Drift Signals

Only token audit or unit snapshots offered as interaction proof
Active nav color with no aria-current, invisible focus, silent failures
Universal focus traps, arrow-key nav, or combobox filters without pattern fit
An affected STP missing UX Coverage or an exclusion with no reason

Practices by activity

Agents working in any of these activities inherit the practices below through runtime work context, such as a DDx bead context digest.

Requirements

For affected UI work, record applicable patterns and stable story AC IDs in STP UX Coverage; verify behavior on the running system, not by prose or token audit.
Cover navigation, keyboard/overlays, async actions, forms, data states and destructive actions where applicable; exclude absent patterns with concrete reasons.
Stories describe observable outcomes: keyboard completion, current location, failure recovery and safe destructive behavior as applicable.

Design

DESIGN.md names the visible active cue and semantic state, visible keyboard focus, modal/non-modal behavior, feedback and recovery conventions.
Use native links for ordinary navigation. Composite widgets follow their own keyboard contract; do not require menu arrow keys for ordinary links.
Trap focus only in modal overlays. Dismissal and focus return follow the chosen pattern; when a trigger is deleted, choose a logical successor.
Confirm irreversible/high-impact actions; document reviewed undo for low-risk reversible actions. Preserve form input after failure.
Loading, disabled, empty, error and success states apply only where they exist. Do not require autosave, global search, range selection or a particular loader style in every app.

Implementation

Preserve the chosen component’s keyboard semantics and accessible names. Library absence of a needed widget is a documented design gap, not license to invent its API.
Async controls signal pending state, prevent duplicate requests, and expose recovery after failure. Error feedback must be perceivable without stealing focus unnecessarily.
Derive visible current-location styling from the semantic state or a stable bound token/class; selected tabs use aria-selected.

Testing

Use the STP UX Coverage format in workflows/references/ux-evidence.md. Assert actual outcomes and connect them to stable AC IDs using @covers.
Drive relevant routes, overlays, pending and failure paths through the real surface harness. Link results from the existing STP mapping per workflows/concerns/verification/practices.md.
A structural validator establishes a populated evidence plan only. Review must verify mapped tests exist, cite the AC, and observed results prove the behavior; screenshots may support visual review but cannot replace semantic assertions.

Quality Gates

Affected new/changed UX work has a reviewed UX Coverage map before handoff; legacy omission is an adoption gap, not retroactive structural invalidity.
Every applicable pattern has observed evidence or a reviewed exception with owner, rationale, alternative evidence and review trigger. No audit-green-only interaction claim.

Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition: model-primary
Issuer: HELIX helix
Signing key: ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source: concerns/ux-interaction-patterns.md
Signed: 2026-10-22T18:09:54Z
Content digest: sha256:7843b2e4…624294e2

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON

{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-10-22T18:09:54Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/concerns/ux-interaction-patterns/",
        "digest": {
          "alg": "sha256",
          "value": "7843b2e49d3e2e9d578388fc10886e779f1ee4c82e0a3a2400c2a3b7624294e2"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "zhwMGvXaP7IDQCMJpzuti4iJpoLe1Bumf00SORIpVhXm8nTOgglp55lGuDgyma_Y-4HVzsPb2k-Y5Vv9EJH3Dg",
      "signed_at": "2026-10-22T18:09:54Z"
    }
  ]
}

attestation file · issuer keys