Skip to content

crud_component investigation findings and recommendations

This issue documents the findings and recommendations following the audit completed in #2933 (closed).

Preamble

crud_component was created by groupux paper cuts a year ago (gitlab-org/gitlab!156749 (merged)) as "a list container being used to host a table or list with user actions such as create, read, update, delete".

Today, after attempts to add it to the design system, it is not clearly owned by a single domain team.

It contains complex interactions and behaviours that would be hard to implement consistently without a shared resource.

image.png

Example crud_component used to manage instance OAuth applications.

Initial implementations were consistent and tightly scoped but current usage is diverging in multiple ways. Some of the observed divergences could negatively impact usability and learnability if they don't meet user expectations.

Today, teams are asking for guidance for how to use it (https://gitlab.com/gitlab-org/ux-research/-/issues/3571).

There is A LOT of crud_component usage

The vue and haml crud_component implementations are used in over 100 places in GitLab. Usage is increasing as more and more teams lean into the style and features it offers.

We can support users and feature teams by formalising the emerging patterns, creating actionable guidance, and providing assets to make them easier to work with.

List/tabular contents with some CRUD actions make up over half of current usage

Examples with full CRUD actions include active project access tokens, CI/CD variables, and GitLab pages domains.

image.png

Example of a crud_component with full CRUD actions

Within these usages there are some other insights we should dig into further as a team:

  • Solutions for small tabular data were often bespoke.
  • Lack of a shared solution for list-like data.
  • Inconsistent states and view behaviours.
  • Instances of the container being used as the only item on a page.

Instances with partial management were more common

Not all implementations offered full CRUD actions. Instances were observed where:

  • Creation happened outside of the GitLab UI, options to remove and lock only (terraform states, Gitaly servers, file hooks).
  • Creation happened elsewhere in the UI, option to delete only (deployments).
  • Creation happened elsewhere on the same page, list linked to update settings (instance level integrations).
  • Creation and update, but no delete (CI/CD job token allowlist).
  • Creation and deletion, but no update (Secure files).

image.png

Example of a read and delete only list

Additionally many partial management instances were read-only, such as MR dashboard, admin > group > projects list, instance runners.

These read only instances likely benefit from a simpler component, and shared list and table styles.

Create patterns vary significantly between instances

Where a create action was provided patterns observed include:

  • Form built into component.
  • Trigger a form in a drawer.
  • Trigger a form in a modal.
  • Link to a new page.

image.png

Example of the form built into the component

Usage with no CRUD actions account for an estimated 1/4 of instances

These instances are a cause for concern and act as clues for gaps in the design system.

The instances that didn't meet the definition ("a list container being used to host a table or list with user actions such as create, read, update, delete") can mostly be grouped into the following buckets:

  • Collapsable container to reveal more information about a single item.
  • Visible form section container.
  • Container for a single item with one or more actions.
  • Visible container, often on the same page as other CRUD components.

image.png

Example of a container for a single item with actions

Recommendations

Based on this audit, I'd like to make the following recommendations for the design system team:

  • Add a pattern to the design system to create and manage a list of items in a particular context.
    • This can guide teams building this functionality into their features and point towards component based solutions.
  • Add a component to the design system to support teams working with this pattern.
    • This could provide a partial migration path for up to 60% of existing crud_component usages.
  • Add guidance and assets to assist in the creation and display of tabular data, especially in a condensed space.
    • These can be used as content for creating and managing a list of items, but also becomes more important as upcoming layout changes will require more condensed views.
  • Add guidance and assets to assist in the creation and display of 'rich' lists of items, especially in a condensed space.
    • These can be used as content for creating and managing a list of items, but also becomes more important as upcoming layout changes will require more condensed views.
  • Formalise a collapsable container where existing options aren't meeting team needs.
    • This could provide a partial migration path for some non-crud instances, and support upcoming priority work for feature teams.
  • Formalise form sectioning guidance.
    • This could provide a partial migration path for some non-crud instances and matches previous sentiment survey feedback around forms.
  • Add guidelines and assets to create and manage a list of items when it is the only item on a page and not part of a wider context.
    • This could provide a less boxy experience to these pages (currently limited to the admin area).

Read more

Edited by Dan MH