[Design + FE dev] Organize permissions into grouped sections in the UX when creating or editing a custom role.

Problem to solve

When a user creates a custom role, they are presented with a long list of permissions. This list will continue to grow and cause cognitive overload when creating a custom role.

Design exploration

We decided to group permissions into meaningful sections, so the user can quickly select permissions. When permissions are grouped or collapsed, it should highlight how many permissions are selected. The plan of work:

• Evaluate current functional groupings against user's mental model (https://gitlab.com/gitlab-org/ux-research/-/issues/3318)
• Propose improvement to permission selector UX:
  • Functional grouping - groupings should be 1:1 with groupings in the roles and permissions documentation.
  • Dependencies - consistent and fluid interaction when one permission is required (eg admin vulnerability and read vulnerability)
  • Search and filtering
• Validate proposed designs

Other opportunities:

• Templating based on commonly used permissions (current role use data would be valuable here)

Permission use cases to design for:

• Dependent permissions within and across a resource group
• Base permissions included default role
• Broad --> Fine grained permissions
• Groupings functional, feature or scope
• Description

Prototypes
Option 1 - Edit / Filled permissions
Option 2 - Simple functional grouping with expandable areas
Option 3 - Searchable select permissions from drawer Option 3A - Searchable select with non-hierarchical grouping
Option 4 - Permission transfer

Solution Validation

✅ After conducting unmoderated usability test with prototypes for the current experience, proposed experience and improved proposed experience, we are confident in moving forward with the proposed designs.

Results 1: We tested the current and 2 proposed experiences for selecting permissions. Results showed 100% task completion across all experiences but a simple flat grouping merged as the most efficient and usable, with necessary improvements like search and task-based groupings.

Results 2: We tested Flat Grouping design with improvements and it proved highly successful, maintaining 100% task completion rates and high usability scores (4.9/5). As additional enhancement to the experience, users suggested refining the visual indicators for required dependencies and sub-permission to make relationships even clearer.

📖 Dig into findings here: https://gitlab.com/gitlab-org/ux-research/-/issues/3318+

Final Design and Specs

Iteration 1: Permission grouping changes,

Before	After	Final Designs
Grouping Permissions - Permissions are ungrouped in New Role > Select permissions area	Permissions are grouped with the same system based functional groupings as outlined in default permissions documentation Chevron to expand / unexpand section. Default state, all groups are expanded. Checked permission changes the count of permissions selected Permissions are ordered by functional grouping, then, first alphabetically by resource, then alphabetically by action
Finer grained permissions that are included under broader permission (eg manage includes view) Selected with permission No apparent organization	Nest fine permissions under the broad permission Selecting the checkbox for broad permissions automatically selects the fine permissions below it Add tree connector to maintain visual indicator of hierarchy and When only one or few permissions under broad permission is selected, checkbox for broad permission is changed to "indeterminate" state
Inherited permission from base role Pre-selected after choosing base role	No change in pre-selection Indicate badge with neutral muted that the permission has been added from [default role] Checkbox is disabled
Required permission across functional grouping Selected with permission selection	Keep pre selection the same (pre-select with permission) Required permission checkbox is disabled Unselect required permission when unselecting its paired permission, unless it was selected by user prior to Add a badge in warning state with a popover to give visual indication why permission has been selected Tooltip on badge hover, list out all permissions where this permission is required: This permission must be enabled when using [dependent permission]
Description Outlined in table	Disclose when user clicks information icon Popover has detail description Popover is dismissible

Iteration 2: Functionality improvements

Before	After	Final Designs
Functionality in Permission Selection Flat table with no ability to review and confirm selection	Add dynamic search and filter function by keywords to filter list. Add component to list out selected permissions List out permission in this order: selected, required and added from default role Include all badges in the list

Follow-up and Next Steps

• Follow-up: An insight unaddressed is changing grouping permissions to be task-based rather than system-based. I recommend we reevaluate once we better understand the UX implications, created an actionable insight to track: https://gitlab.com/gitlab-org/gitlab/-/issues/519128
• We'll look into how to gather feedback from the experience here