# Relationship management

Relationship management is the canonical editing pattern for connecting one record to many assets, people, groups, controls, or other records.

## When to use

Use a dedicated relationship page when users need to search, compare, add, and remove several records in one save operation. A searchable select remains appropriate for one or two lightweight choices.

## Layout

- Use one full-width panel inside the standard page frame.
- On wide screens, split the panel into available and selected columns of equal visual weight.
- Stack available records before selected records on narrow screens.
- Keep search and result scrolling inside the available column so the page header and save actions remain stable.
- Give both columns a useful minimum height so the empty state does not collapse the workflow.

## Available records

- Place a compact search field before the available list.
- Make each result row a button or checkbox-backed label with a visible hover and focus state.
- Show the primary label first and a stable identifier or relevant relationship metadata second.
- Adding a record updates the selected column immediately without saving yet.

## Selected records

- Keep selected rows in the same order until the user deliberately changes it or the domain requires sorting.
- Give removal its own accessible name, such as `Remove Finance group`.
- When no records are selected, center an explicit message such as `Items selected for this record will appear here.`
- Do not use destructive styling for removal from an unsaved relationship set; it is an editable choice, not record deletion.

## Save boundary

Treat the entire relationship set as one save boundary. Put Cancel and Save after both columns, keep them visible after validation errors, and warn before leaving only when there are unsaved changes.

## Accessibility

- Associate search with the result set it filters.
- Announce additions and removals through a polite status region.
- Preserve logical focus after a row moves between columns.
- Do not rely on color to distinguish available and selected rows.

## Product boundary

Relationship types, eligibility, maximum selections, ordering rules, validation, and persistence remain application-owned.