doc/user/project/issues/design_management.md
{{< details >}}
{{< /details >}}
<!--- end_remove -->[!warning] This feature was deprecated in GitLab 18.6 and is planned for removal in 20.0. This change is a breaking change. In GitLab 20.0 and later, users are no longer able to upload new designs. Existing designs remain available in read-only mode until GitLab 21.0, giving users time to save their designs as needed. GitLab is exploring alternatives that better integrate with the tools designers already use.
With Design Management you can upload design assets (including wireframes and mockups) to GitLab issues and keep them stored in a single place. Product designers, product managers, and engineers can collaborate on designs with a single source of truth.
You can share mockups of designs with your team, or visual regressions can be viewed and addressed.
<i class="fa-youtube-play" aria-hidden="true"></i> For a video overview, see Design Management.
<!-- Video published on 2019-07-11 -->{{< history >}}
{{< /history >}}
Git Large File Storage (LFS) must be enabled:
Designs are stored as LFS objects. Image thumbnails are stored as other uploads, and are not associated with a project but rather with a specific design model.
A GitLab administrator can verify the relative path of a hashed-stored project by going to Admin > Projects
and then selecting the project in question. The Relative path field contains @hashed in its value.
If the requirements are not met, you are notified in the Designs section.
You can upload files of the following types as designs:
Support for PDF files is tracked in issue 32811.
The Designs section is in the issue description.
Prerequisites:
To view a design:
The design you selected opens. You can then zoom in on it or create a comment.
When viewing a design, you can move to other designs. To do so, either:
To return to the issue view, either:
When a design is added, a green icon ({{< icon name="plus-square" >}}) is displayed on the image thumbnail. When a design has been changed in the current version, a blue icon ({{< icon name="file-modified-solid" >}}) is displayed.
You can explore a design in more detail by zooming in and out of the image:
+) and minus (-)
at the bottom of the image.To move around the image while zoomed in, drag the image.
{{< history >}}
{{< /history >}}
Prerequisites:
To add a design to an issue:
Select Upload designs and then select images from your file browser. You can select up to 10 files at once.
<!-- vale gitlab_base.SubstitutionWarning = NO -->Select click to upload and then select images from your file browser. You can select up to 10 files at once.
<!-- vale gitlab_base.SubstitutionWarning = YES -->Drag a file from your file browser and drop it in the drop zone in the Designs section.
Take a screenshot or copy a local image file into your clipboard, hover your cursor over the drop zone, and press <kbd>Control</kbd> or <kbd>Command</kbd>+<kbd>V</kbd>.
When pasting images like this, keep the following in mind:
design_<timestamp>.png.{{< history >}}
{{< /history >}}
As discussion on a design continues, you might want to upload a new version of a design.
Prerequisites:
To do so, add a design with the same filename.
To browse all the design versions, use the dropdown list at the top of the Designs section. It's shown as either Showing latest version or Showing version #N.
When you upload an image with the same filename as an existing uploaded design and that is the same, it's skipped. This means that no new version of the design is created. When designs are skipped, a warning message is displayed.
{{< history >}}
{{< /history >}}
You can archive individual designs or select a few of them to archive at once.
Archived designs are not permanently lost. You can browse previous versions.
When you archive a design, its URL changes. If the design isn't available in the latest version, you can link to it only with the version in the URL.
Prerequisites:
To archive a single design:
To archive multiple designs at once:
Design Management data can be replicated and in GitLab 16.1 and later it can be verified by Geo as well.
{{< history >}}
content_editor_on_issues. Disabled by default.content_editor_on_issues removed in GitLab 16.5.{{< /history >}}
You can use the Markdown and rich text editor in design descriptions. It's the same editor you use for comments across GitLab.
You can change the order of designs by dragging them to a new position.
You can start discussions on uploaded designs. To do so:
You can adjust a pin's position by dragging it around the image. Use this when your design's layout has changed, or to move a pin so you can add a new one in its place.
New discussion threads get different pin numbers, which you can use to refer to them.
New discussions are output to the issue activity, so that everyone involved can participate in the discussion.
{{< history >}}
{{< /history >}}
Prerequisites:
To delete a comment from a design:
When you're done discussing part of a design, you can resolve the discussion thread.
To mark a thread as resolved or open, either:
Resolving a discussion thread also marks any pending to-do items related to notes inside the thread as done. Only to-do items for the user triggering the action are affected.
Your resolved comment pins disappear from the design to free up space for new discussions. To revisit a resolved discussion, expand Resolved Comments below the visible threads.
To add a to-do item for a design, select Add a to-do item on the design sidebar.
You can refer to a design in a Markdown text box. Paste the raw URL of the design in a comment or description. It's then displayed as a short reference.
For example, if you refer to a design as:
See https://gitlab.com/gitlab-org/gitlab/-/issues/13195/designs/Group_view.png.
GitLab automatically renders raw URLs as an abbreviated reference:
Linking to an image differs from embedding the image in a comment or description. It's not possible to embed a design this way.
User activity events on designs (creation, deletion, and updates) are tracked by GitLab and displayed on the user profile, group, and project activity pages.
You can use the GitLab-Figma plugin to upload your designs from Figma directly to your issues in GitLab.
To use the plugin in Figma, install it from the Figma directory and connect to GitLab through a personal access token.
For more information, see the plugin documentation.
When working with Design Management, you might encounter the following issues.
You might get an error that states Could not find design.
This issue occurs when a design has been archived, so it's not available in the latest version, and the link you've followed doesn't specify a version.
When you archive a design, its URL changes. If the design isn't available in the latest version, it can be linked to only with the version in the URL.
For example, https://gitlab.example.com/mygroup/myproject/-/issues/123456/designs/menu.png?version=503554.
You can no longer access menu.png with https://gitlab.example.com/mygroup/myproject/-/issues/123456/designs/menu.png.
The workaround is to select one of the previous versions from the dropdown list at the top of the Designs section. It's shown as either Showing latest version or Showing version #N.
Issue 392540 tracks improving this behavior.