Permissions Matrix

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.

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.

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.