Skip to content

UX Interaction Patterns (Radix)

Category: Quality Attributes · Areas: ui, frontend

Description

Category

quality-attribute

Areas

ui, frontend

Boundary

This concern owns the Radix/shadcn implementation choice per ADR-011. It composes ux-interaction-patterns for framework-neutral behavior; the resolver and context-digest loader include that baseline for existing ux-radix selections. No selection migration or new exclusive slot is required.

Components

  • Radix accessible primitives, wrapped by copied shadcn/ui components
  • WAI-ARIA patterns appropriate to the actual widget
  • Boundary: ux-radix owns the widgets; a11y-wcag-aa owns the accessibility checks.

Constraints

  • Copy shadcn components into components/ui/ and theme them with project tokens; shadcn is not installed as an npm dependency. Keep Radix semantics intact.
  • Ordinary nav uses semantic nav/links; NavigationMenu is optional when its interaction fits. Plain text filtering is not automatically a combobox.
  • Dialog/AlertDialog implement modal decisions. Popover may be non-modal; focus trapping follows modality, not an unconditional overlay rule.
  • Match tabs, selects, menus, tooltips and disclosure to their actual patterns. Tooltips contain no interactive content; use a popover for interactive detail.
  • packaged-design-system and databricks-appkit-ui have competing component ownership; resolve any composition in project overrides with governing ADR before build.

When to use

A project choosing Radix/shadcn as its UI implementation. For another component library select ux-interaction-patterns and its library concern instead. Existing ux-radix selections retain the neutral baseline automatically.

Artifact Impact

Selecting this concern requires these artifacts to change (a selected concern absent from them is drift):

  • DESIGN_SYSTEM: component mappings and app conventions per ux-interaction-patterns
  • TEST_PLAN: baseline UX Coverage plus applicable Radix keyboard/focus tests

ADR References

Selecting this concern needs no ADR; concerns.md records it. Write an ADR only when the project deviates from the Radix/shadcn prescription. Neutral interaction behavior composes separately.

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

  • Apply ux-interaction-patterns and its STP UX Coverage map to affected UI work; existing ux-radix selections load that baseline automatically.
  • Use copied shadcn/ui components on Radix; preserve pattern-appropriate keyboard behavior, visible focus and modal focus return.

Design and Implementation

  • ux-radix remains the canonical owner of the Radix/shadcn prescription per ADR-011. Framework concerns reference the selected component owner.
  • Customize copied components to project tokens without breaking Radix handlers.
  • Use Dialog/AlertDialog for modal decisions; Popover defaults can be non-modal. Trap focus only for modal behavior; name overlays and restore focus logically.
  • Use native anchors/landmarks for ordinary navigation. NavigationMenu is a choice, not a requirement for every nav. Use Tabs for same-page panels and Select/RadioGroup for matching choices. Combobox applies to selectable search suggestions, not every text filter. Tooltips are non-interactive hints.
  • Library-specific convenience patterns (command palettes, autosave, range selection) require product scope; do not introduce them as baseline obligations.
  • Resolve AppKit or packaged design system component ownership before implementation. No silently installed second library or duplicated token system.

Testing and Quality Gates

  • Apply the neutral baseline’s actual runtime interaction evidence, including visible active nav with aria-current=“page” where page navigation exists.
  • Verify applicable Radix Escape, keyboard movement and modal focus-return behavior; a component import or screenshot alone does not prove behavior.
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-radix.md
Signed
2026-11-16T15:52:45Z
Content digest
sha256:8f9edc0c…4c0818c8

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-11-16T15:52:45Z",
    "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-radix/",
        "digest": {
          "alg": "sha256",
          "value": "8f9edc0cebb83776a7b7e940085996b9beb8d95fa4f1d7fe60a67c754c0818c8"
        }
      }
    ],
    "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": "JuVYIwubiWqPpTnYMxKKpV92lky_GTXos4_-QDefJLIOLeTNWktVdkjDRosc-P0AqUToXvDIHBvX4x7MmuV9AQ",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}