Add latest changes from gitlab-org/gitlab@14-4-stable-eev14.4.0-rc42

3 files changed, 124 insertions, 36 deletions

diff --git a/doc/development/contributing/design.md b/doc/development/contributing/design.md
index 9e8375fcbdd..e85f5dd8349 100644
--- a/doc/development/contributing/design.md
+++ b/doc/development/contributing/design.md
@@ -5,34 +5,119 @@ group: Development
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
 
-# Implement design & UI elements
+# Design and user interface changes
 
-For guidance on UX implementation at GitLab, please refer to our [Design System](https://design.gitlab.com/).
+Follow these guidelines when contributing or reviewing design and user interface
+(UI) changes. Refer to our [code review guide](../code_review.md) for broader
+advice and best practices for code review in general.
 
-The UX team uses labels to manage their workflow.
+The basis for most of these guidelines is [Pajamas](https://design.gitlab.com/),
+GitLab design system. We encourage you to [contribute to Pajamas](https://design.gitlab.com/get-started/contribute/)
+with additions and improvements.
 
-The `~UX` label on an issue is a signal to the UX team that it will need UX attention.
-To better understand the priority by which UX tackles issues, see the [UX section](https://about.gitlab.com/handbook/engineering/ux/) of the handbook.
+## Merge request reviews
 
-Once an issue has been worked on and is ready for development, a UXer removes the `~UX` label and applies the `~"UX ready"` label to that issue.
+As a merge request (MR) author, you must include _Before_ and _After_
+screenshots (or videos) of your changes in the description, as explained in our
+[MR workflow](merge_request_workflow.md). These screenshots/videos are very helpful
+for all reviewers and can speed up the review process, especially if the changes
+are small.
 
-There is a special type label called `~"product discovery"` intended for UX (user experience),
-PM (product manager), FE (frontend), and BE (backend). It represents a discovery issue to discuss the problem and
-potential solutions. The final output for this issue could be a doc of
-requirements, a design artifact, or even a prototype. The solution will be
-developed in a subsequent milestone.
+## Checklist
 
-`~"product discovery"` issues are like any other issue and should contain a milestone label, `~Deliverable` or `~Stretch`, when scheduled in the current milestone.
+Check these aspects both when _designing_ and _reviewing_ UI changes.
 
-The initial issue should be about the problem we are solving. If a separate [product discovery issue](https://about.gitlab.com/handbook/engineering/ux/ux-department-workflow/#how-we-use-labels)
-is needed for additional research and design work, it will be created by a PM or UX person.
-Assign the `~UX`, `~"product discovery"` and `~Deliverable` labels, add a milestone and
-use a title that makes it clear that the scheduled issue is product discovery
-(for example, `Product discovery for XYZ`).
+### Writing
 
-In order to complete a product discovery issue in a release, you must complete the following:
+- Follow [Pajamas](https://design.gitlab.com/content/punctuation/) as the primary
+  guidelines for UI text and [documentation style guide](../documentation/styleguide/index.md)
+  as the secondary.
+- Use clear and consistent [terminology](https://design.gitlab.com/content/terminology/).
+- Check grammar and spelling.
+- Consider help content and follow its [guidelines](https://design.gitlab.com/usability/helping-users/).
+- Request review from the [appropriate Technical Writer](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers),
+  indicating any specific files or lines they should review, and how to preview
+  or understand the location/context of the text from the user's perspective.
 
-1. UXer removes the `~UX` label, adds the `~"UX ready"` label.
-1. Modify the issue description in the product discovery issue to contain the final design. If it makes sense, the original information indicating the need for the design can be moved to a lower "Original Information" section.
-1. Copy the design to the description of the delivery issue for which the product discovery issue was created. Do not simply refer to the product discovery issue as a separate source of truth.
-1. In some cases, a product discovery issue also identifies future enhancements that will not go into the issue that originated the product discovery issue. For these items, create new issues containing the designs to ensure they are not lost. Put the issues in the backlog if they are agreed upon as good ideas. Otherwise leave them for triage.
+### Patterns
+
+- Consider similar patterns used in the product and justify in the issue when diverging
+  from them.
+- Use appropriate [components](https://design.gitlab.com/components/overview/)
+  and [data visualizations](https://design.gitlab.com/data-visualization/overview/).
+
+### Visual design
+
+Check visual design properties using your browser's _elements inspector_ ([Chrome](https://developer.chrome.com/docs/devtools/css/),
+[Firefox](https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Open_the_Inspector)).
+
+- Use recommended [colors](https://design.gitlab.com/product-foundations/colors/)
+  and [typography](https://design.gitlab.com/product-foundations/type-fundamentals/).
+- Follow [layout guidelines](https://design.gitlab.com/layout/grid/).
+- Use existing [icons](http://gitlab-org.gitlab.io/gitlab-svgs/) and [illustrations](http://gitlab-org.gitlab.io/gitlab-svgs/illustrations/)
+  or propose new ones according to [iconography](https://design.gitlab.com/product-foundations/iconography/)
+  and [illustration](https://design.gitlab.com/product-foundations/illustration/)
+  guidelines.
+- _Optionally_ consider [dark mode](../../user/profile/preferences.md#dark-mode). [^1]
+
+ [^1]: You're not required to design for [dark mode](../../user/profile/preferences.md#dark-mode) while the feature is in [alpha](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha). The [UX Foundations team](https://about.gitlab.com/direction/ecosystem/foundations/) plans to improve the dark mode in the future. Until we integrate [Pajamas](https://design.gitlab.com/) components into the product and the underlying design strategy is in place to support dark mode, we cannot guarantee that we won't introduce bugs and debt to this mode. At your discretion, evaluate the need to create dark mode patches.
+
+### States
+
+Check states using your browser's _styles inspector_ to toggle CSS pseudo-classes
+like `:hover` and others ([Chrome](https://developer.chrome.com/docs/devtools/css/reference/#pseudo-class),
+[Firefox](https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector/How_to/Examine_and_edit_CSS#viewing_common_pseudo-classes)).
+
+- Account for all applicable states ([error](https://design.gitlab.com/content/error-messages),
+  rest, loading, focus, hover, selected, disabled).
+- Account for states dependent on data size ([empty](https://design.gitlab.com/regions/empty-states),
+  some data, and lots of data).
+- Account for states dependent on user role, user preferences, and subscription.
+- Consider animations and transitions, and follow their [guidelines](https://design.gitlab.com/product-foundations/motion/).
+
+### Responsive
+
+Check responsive behavior using your browser's _responsive mode_ ([Chrome](https://developer.chrome.com/docs/devtools/device-mode/#viewport),
+[Firefox](https://developer.mozilla.org/en-US/docs/Tools/Responsive_Design_Mode)).
+
+- Account for resizing, collapsing, moving, or wrapping of elements across
+  all breakpoints (even if larger viewports are prioritized).
+- Provide the same information and actions in all breakpoints.
+
+### Accessibility
+
+Check accessibility using your browser's _accessibility inspector_ ([Chrome](https://developer.chrome.com/docs/devtools/accessibility/reference/),
+[Firefox](https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector#accessing_the_accessibility_inspector)).
+
+- Conform to level AA of the World Wide Web Consortium (W3C) [Web Content Accessibility Guidelines 2.1](https://www.w3.org/TR/WCAG21/),
+  according to our [statement of compliance](https://design.gitlab.com/accessibility/a11y/).
+- Follow accessibility [best practices](https://design.gitlab.com/accessibility/best-practices/)
+  and [checklist](../fe_guide/accessibility.md#quick-checklist).
+
+### Handoff
+
+When the design is ready, _before_ starting its implementation:
+
+- Share design specifications in the related issue, preferably through a [Figma link](https://help.figma.com/hc/en-us/articles/360040531773-Share-Files-with-anyone-using-Link-Sharing#Copy_links)
+  link or [GitLab Designs feature](../../user/project/issues/design_management.md#the-design-management-section).
+  See [when you should use each tool](https://about.gitlab.com/handbook/engineering/ux/product-designer/#deliver).
+- Document user flow and states (for example, using [Mermaid flowcharts in Markdown](../../user/markdown.md#mermaid)).
+- Document animations and transitions.
+- Document responsive behaviors.
+- Document non-evident behaviors (for example, field is auto-focused).
+- Document accessibility behaviors (for example, using [accessibility annotations in Figma](https://www.figma.com/file/g7QtDbfxF3pCdWiyskIr0X/Accessibility-bluelines)).
+- Contribute new icons or illustrations to the [GitLab SVGs](https://gitlab.com/gitlab-org/gitlab-svgs)
+  project.
+
+### Follow-ups
+
+At any moment, but usually _during_ or _after_ the design's implementation:
+
+- Contribute [issues to Pajamas](https://design.gitlab.com/get-started/contribute#contribute-an-issue)
+  for additions or enhancements to the design system.
+- Create issues with the [`~UX debt`](issue_workflow.md#technical-and-ux-debt)
+  label for intentional deviations from the agreed-upon UX requirements due to
+  time or feasibility challenges, linking back to the corresponding issue(s) or
+  MR(s).
+- Create issues for [feature additions or enhancements](issue_workflow.md#feature-proposals)
+  outside the agreed-upon UX requirements to avoid scope creep.
diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md
index 29f6eb57160..d0f107ba98a 100644
--- a/doc/development/contributing/issue_workflow.md
+++ b/doc/development/contributing/issue_workflow.md
@@ -151,7 +151,7 @@ From the handbook's
 page:
 
 > Categories are high-level capabilities that may be a standalone product at
-another company. e.g. Portfolio Management.
+another company, such as Portfolio Management, for example.
 
 It's highly recommended to add a category label, as it's used by our triage
 automation to
@@ -182,7 +182,7 @@ From the handbook's
 [Product stages, groups, and categories](https://about.gitlab.com/handbook/product/categories/#hierarchy)
 page:
 
-> Features: Small, discrete functionalities. e.g. Issue weights. Some common
+> Features: Small, discrete functionalities, for example Issue weights. Some common
 features are listed within parentheses to facilitate finding responsible PMs by keyword.
 
 It's highly recommended to add a feature label if no category label applies, as
@@ -303,7 +303,7 @@ We automatically add the ~"Accepting merge requests" label to issues
 that match the [triage policy](https://about.gitlab.com/handbook/engineering/quality/triage-operations/#accepting-merge-requests).
 
 We recommend people that have never contributed to any open source project to
-look for issues labeled `~"Accepting merge requests"` with a [weight of 1](https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None&sort=weight&weight=1) or the `~"Good for new contributors"` [label](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&state=opened&label_name[]=good%20for%20new%20contributors&assignee_id=None) attached to it.
+look for issues labeled `~"Accepting merge requests"` with a [weight of 1](https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None&sort=weight&weight=1) or the `~"good for new contributors"` [label](https://gitlab.com/gitlab-org/gitlab/-/issues?scope=all&state=opened&label_name[]=good%20for%20new%20contributors&assignee_id=None) attached to it.
 More experienced contributors are very welcome to tackle
 [any of them](https://gitlab.com/groups/gitlab-org/-/issues?state=opened&label_name[]=Accepting+merge+requests&assignee_id=None).
 
@@ -342,19 +342,22 @@ To create a feature proposal, open an issue on the
 [issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues).
 
 In order to help track the feature proposals, we have created a
-[`feature`](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name=feature) label. For the time being, users that are not members
-of the project cannot add labels. You can instead ask one of the [core team](https://about.gitlab.com/community/core-team/)
-members to add the label ~feature to the issue or add the following
+[`feature`](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name=feature) label.
+For the time being, users that are not members of the project cannot add labels.
+You can instead ask one of the [core team](https://about.gitlab.com/community/core-team/)
+members to add the label `~feature` to the issue or add the following
 code snippet right after your description in a new line: `~feature`.
 
 Please keep feature proposals as small and simple as possible, complex ones
 might be edited to make them small and simple.
 
-Please submit Feature Proposals using the ['Feature Proposal' issue template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal%20-%20detailed.md) provided on the issue tracker.
+Please submit feature proposals using the ['Feature Proposal' issue template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal%20-%20detailed.md) provided on the issue tracker.
 
-For changes in the interface, it is helpful to include a mockup. Issues that add to, or change, the interface should
-be given the ~"UX" label. This will allow the UX team to provide input and guidance. You may
-need to ask one of the [core team](https://about.gitlab.com/community/core-team/) members to add the label, if you do not have permissions to do it by yourself.
+For changes to the user interface (UI), follow our [design and UI guidelines](design.md),
+and include a visual example (screenshot, wireframe, or mockup). Such issues should
+be given the `~UX"` label for the Product Design team to provide input and guidance.
+You may need to ask one of the [core team](https://about.gitlab.com/community/core-team/)
+members to add the label, if you do not have permissions to do it by yourself.
 
 If you want to create something yourself, consider opening an issue first to
 discuss whether it is interesting to include this in GitLab.
diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md
index 25561764bd6..a521d89db2b 100644
--- a/doc/development/contributing/merge_request_workflow.md
+++ b/doc/development/contributing/merge_request_workflow.md
@@ -18,8 +18,8 @@ in order to ensure the work is finished before the release date.
 
 If you want to add a new feature that is not labeled, it is best to first create
 an issue (if there isn't one already) and leave a comment asking for it
-to be marked as `Accepting Merge Requests`. Please include screenshots or
-wireframes of the proposed feature if it will also change the UI.
+to be marked as `Accepting merge requests`. See the [feature proposals](issue_workflow.md#feature-proposals)
+section.
 
 Merge requests should be submitted to the appropriate project at GitLab.com, for example
 [GitLab](https://gitlab.com/gitlab-org/gitlab/-/merge_requests),
@@ -255,14 +255,14 @@ requirements.
 1. The change is tested in a review app where possible and if appropriate.
 1. The new feature does not degrade the user experience of the product.
 1. The change is evaluated to [limit the impact of far-reaching work](https://about.gitlab.com/handbook/engineering/development/#reducing-the-impact-of-far-reaching-work).
-1. An agreed-upon rollout plan.  
+1. An agreed-upon [rollout plan](https://about.gitlab.com/handbook/engineering/development/processes/rollout-plans/).  
 1. Merged by a project maintainer.
 
 ### Production use
 
 1. Confirmed to be working in staging before implementing the change in production, where possible.
 1. Confirmed to be working in the production with no new [Sentry](https://about.gitlab.com/handbook/engineering/#sentry) errors after the contribution is deployed.
-1. Confirmed that the rollout plan has been completed.
+1. Confirmed that the [rollout plan](https://about.gitlab.com/handbook/engineering/development/processes/rollout-plans) has been completed.
 1. If there is a performance risk in the change, I have analyzed the performance of the system before and after the change.
 1. *If the merge request uses feature flags, per-project or per-group enablement, and a staged rollout:*
    - Confirmed to be working on GitLab projects.