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-radixowns the widgets;a11y-wcag-aaowns 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"
}
]
}