Update forms and form validation across GitLab
Problem to solve
Make form validation on GitLab user-friendly. Right now, error messages appear in alert message boxes on top of the page (just below the nav bar). Often, the messages are generic and not helpful to users. I also noticed examples where the error message box appears on the top of the page but I wasn't able to see it because the form that I was working with was way below the fold.
Common problems:
- Error messages appear below the nav bar, not anywhere close to the piece of information the users are interacting with. Law of proximity should be applied to make it clear to users that the error message is related to the information they're interacting with.
- We have expandable sections in settings pages. When an error happens, all sections get collapsed and the error message appears below the nav bar. This is yet another obstruction for users to overcome to simply understand what is going on.
- When error messages don't need a page reload to show up, they sometimes don't get noticed because the browser window doesn't scroll to the top. With form validation errors that show up below input fields, we only need to scroll to the first error in the form.
- because of the positioning of the error messages, they are sometimes generic and not helpful to users. Moving them below the input fields alone will make them more contextual. But we should always strive to write error messages that are helpful.
- we rarely use inline (live) form validation that could help users fill in the right information in the right format without the need to submit the form and without a page reload.
- Input field labels are often missing (only placeholder is present) or they're positioned to the left of the input fields. Our new guidelines require labels to be always present and positioned on top of input fields.
Further details
Our guidelines for forms and form validation have been updated to deal with these problems and make forms in GitLab user-friendly. Most examples aren't yet reflected in code snippets in the design system but the guidelines are aligned with the design library that the UX department uses.
GitLab forms and form validation audit (Google Spreadsheet)
Form measure specs (based on Design library)
Proposal
Originally, this issue was a continued discussion:
The purpose of this issue is to continue the discussion that the UX department started in the UX weekly call (Oct 16, notes) and involve others (most importantly frontend people).
The proposal of this issue is to remove the old form validation (shown above forms, non contextual), example:
with contextual, inline errors like this:
which is based on our updated form and form validation design guidelines
Frontend vs backend form validation
No matter what type of validation is used (FE vs BE), the user should experience a consistent form validation. This is not a discussion about real-time validation vs validation on reload. It's about making form validation errors easier to understand by making them contextual. Context comes from the positioning of error messages. We can keep the types of validation untouched, as long as we can deliver the change in error messages.
Approach
I conducted a form and form validation audit across GitLab and wrote down all cases that need to be changed in the following spreadsheet. Current state is documented there as well as the desired state.
I also split the cases into 4 priorities:
- Big red box with error message(s) shown above form
- No validation present
- Validation is mostly aligned with guidelines but needs to be made consistent + smaller fixes
- Other smaller fixes
I recommend addressing all cases from a priority group at once so it results in changes that lead to consistency in UX across GitLab (The spreadsheet can be filtered by 4 priorities).
What does success look like, and how can we measure that?
- User-friendly forms that help users fill in the right information and in the correct format without major obstacles (form submit, page reload etc.).
- error messages that are contextual, helpful and shown at the right place.