## When to use

Reach for the matrix when the role count exceeds the rich-picker sweet spot (~5) or when permissions are configurable. For built-in roles only, the summary view is enough — the matrix is the authoring surface, the summary is the runtime surface.

## Editable matrix

Capability per row, role per column, `check-ui` in each cell. Built-in roles (Viewer / Member / Admin / Owner) render `disabled` — they reflect the role's permissions but can't be edited from this surface. The Custom column is the authoring affordance: cells there toggle freely and save on change.

Permissions Changes save automatically

## Read-only role summary

One card per role; `description-list-ui` with capability category as term, list of capabilities as description. Inline tag indicates whether the role is built-in or custom.

Admin Built-in role · 3 members Built-in
Content Read · Comment · Edit own Members Manage members (invite, change role, remove) Workspace All settings except deletion (Owner only)

## Composition rules

- Group capabilities by resource, not alphabetically — "Members: invite / remove / change role" reads cleaner than three rows scattered.
- Built-in role columns are `disabled` — their cells reflect each role's permissions but can't be edited from the matrix. Owner is always fully checked; the others vary.
- The Custom column is the editable surface — that's where the matrix earns its keep over a role-picker. New custom roles append a column to the right.
- Auto-save, don't queue — checkboxes are atomic decisions; a "Save" button at the bottom invites batching errors.
- Use the summary view in tooltips — when a user hovers a role tag in a members table, surface the summary card via popover; don't make them click through to settings.

## See also

- table-ui — grid primitive used for the matrix.
- check-ui — cell primitive (auto-rendered by `type: 'boolean'` columns).
- description-list-ui — summary card layout.
- permissions-role-picker — sibling for role assignment.