Merging GitLab UI into design.gitlab.com: Request For Comments

Within the next few weeks, the groupdesign system team will merge the GitLab UI project into the design.gitlab.com project.

We are doing this to make it easier to use, contribute to and maintain our design system. Easier to use, thanks to better documentation, all in one place. Easier to contribute to and maintain, as documentation and implementation changes can be done in a single merge request rather than several across different projects. For more information, see Unified source of truth for the design system (gitlab-org&15339) and its child items.

To help with this, we are asking two things of you, the reader:

Merge or close your open merge requests in the GitLab UI project by 2025-05-23. If you need to open any merge requests, aim to get them merged before then. If you cannot get them merged by then, it's not the end of the world, as rebasing your changes onto the new repository is straight forward for most changes. It's just easier to not have to do that, by getting them merged soon!
- Note: As of 2025-05-23, the main branch of the GitLab UI project is locked, which means merge requests created there can no longer be merged. See how to migrate your merge requests.
Give feedback on this issue about what we're planning, and about using and contributing to the design system in general. We want make our design system as good as it can be, so any feedback at all from you would be valuable!

To find out more about what we're doing and why, read on!

The plan

To minimise disruption to development, we are planning on announcing a "merging day" for some time in May 2025, during which we will merge the projects. Once we have a firm date, we will announce it in advance so you can prepare for it.

From now until the day before the merging day, nothing will change for you. Though, if you have any open merge requests for GitLab UI, aim to get them merged as soon as possible, or close them.

On the merging day, we will "soft lock" the GitLab UI project. That means that all pushes and merges to all branches will be disallowed. The state of the repository at this point will be what gets moved over to the design.gitlab.com repository. There, it will live under a subdirectory.

After merging day, all development of GitLab UI will be done in the design.gitlab.com repository. That means all merge requests, issues, and so on, will happen in the design.gitlab.com project. Releases of the @gitlab/ui npm package will continue, except they will be built by the design.gitlab.com project.

Once that's done, we'll start moving documentation that lives in Storybook to design.gitlab.com. Our goal is to make https://design.gitlab.com the one place to go to for documentation about our design system.

Eventually, we will archive the GitLab UI project. We won't do that for a while, though, as it has some effects we don't yet want, like tearing down its Pages site.

Questions & answers

Why?

We are doing this to make it easier to use, contribute to and maintain our design system.

Better documentation, with interactive and editable examples will make it easier to use the design system. All information about the design system, from component APIs, to Tailwind classes and design tokens, will live in one place: design.gitlab.com.

It will be easier to contribute to and maintain, as documentation and implementation changes can be done in a single merge request rather than several across different projects.

See gitlab-org&15339 and its child items for more information.

What will change for me?

If you use GitLab UI...

In the short term after merging day, the main change will be where to find Storybook. The current location, https://gitlab-org.gitlab.io/gitlab-ui/, will still be accessible, but it will redirect you to the new location. This is likely to be something like https://design.gitlab.com/storybook, but this is not certain yet.

In the longer term, documentation that you'd normally find in Storybook will be moved to relevant pages within design.gitlab.com. The aim is for this documentation to be more useful, readable and interactive. For instance, we're hoping to build interactive code playgrounds, with actually useful code snippets, unlike what you find with Storybook at the moment. If you're interested in reading about some of the ideas we've had, have a look around in #1992 (closed).

If you contribute to GitLab UI...

All development will happen in the design.gitlab.com project. The code moved from the original GitLab UI project will live in a subdirectory.

We will no longer use semantic commits to manage changelogs and releases. Instead, we'll use changesets. This will have several benefits:

Changelog entries will be reviewable, just like regular code/docs changes, because they're just files. Commit messages aren't reviewable in the same way.
We will be able to enable squash-on-merge again, since the final commit message won't affect the release process.
We will be able to arrange commits in merge requests however makes the most sense, without affecting the release process.
It supports monorepos, which is largely what we expect the design.gitlab.com project to become. That is, in principle, we'll be able to release multiple packages from a single merge request.

What about Storybook?

Storybook will still exist, but it will move to a new location. The current location, https://gitlab-org.gitlab.io/gitlab-ui/, will still be accessible, but it will redirect you to the new location. This is likely to be something like https://design.gitlab.com/storybook, but this is not certain yet.

In the long term, we expect to use Storybook less and less. We'll start by moving component documentation from there to design.gitlab.com. Eventually, with better documentation and interactive examples in design.gitlab.com, there won't be any need to visit Storybook. We will likely continue to use it for CI/testing, but even that isn't certain.

See #1992 (comment 2376605698) for some discussion about this.

What about the `@gitlab/ui` npm package?

The @gitlab/ui npm package will continue to exist and be updated, just like before. The contents of the package will not change. The only difference will be the project from which it is built.

What about open issues and merge requests?

All open issues will be moved to the design.gitlab.com project.

Any remaining open merge requests will need to be recreated on the design.gitlab.com project. For most of them, rebasing the code changes to the new repository should be straight forward (git intelligently handles file moves), and we will provide advice on how to do this. For the trickier cases, we (@markrian) can help you create a new merge request.

How do I migrate my merge request?

There are many ways to do this! If you're not sure which to use, try the simplest way first.

The simplest way: apply the MR patches

# Replace <your_local_design.gitlab.com_clone> with the location
# of your local clone of the design.gitlab.com repository.
cd <your_local_design.gitlab.com_clone>
git fetch

# Replace <your_branch_name> with the name of the branch you want
# to use to create your new merge request. It can be the same name
# as you used for the merge request in the GitLab UI repository,
# but it doesn't have to be!
#
# This assumes your origin remote points to the
# design.gitlab.com repository. If you're not sure, it probably does.
git checkout -b <your_branch_name> --no-track origin/main

# Replace <mr_url> with the GitLab UI merge request URL, e.g., 
# https://gitlab.com/gitlab-org/gitlab-ui/-/merge_requests/123
curl -sSL "<mr_url>".patch | git am --3way

# Push up! This again assumes the origin remote is correct.
git push -o merge_request.create --set-upstream origin

You should then adjust the commit messages, as this repository does not use semantic/conventional commits. Do this with an interactive rebase, or if it is just one commit, use git commit --amend and drop the semantic commits prefix, and use "Sentence case".

If your MR contains something release-worthy, use the yarn run changeset command in the root folder of the design.gitlab.com and follow the prompts. Amend that change to the commit as well and push it up and recreate the MR.

A more involved way: cherry pick

Click to expand

See gitlab-org/gitlab-ui!5172 (comment 2525338505) and https://youtu.be/o-pM5UcvLOM.

A more involved way: rebase

Click to expand

Only use this approach if you know what you're doing. This would go along the lines of:

REMOTE=gitlab-ui
# The name of the branch used in your GitLab UI merge request
BRANCH=<...>
cd <your_local_design.gitlab.com_clone>
git checkout main
git pull --ff-only
git remote add "$REMOTE" https://gitlab.com/gitlab-org/gitlab-ui.git
git config set "remote.$REMOTE.pruneTags" false
git fetch --no-tags "$REMOTE"
git checkout "$BRANCH"
git rebase --onto main "$(git merge-base gitlab-ui/main "$BRANCH")"
git push -o merge_request.create --set-upstream origin

You should then adjust the commit messages, as semantic commits are not needed.

Why not archive GitLab UI to prevent new issues and merge requests?

Eventually, we will archive the GitLab UI project, which will prevent opening of new issues and merge requests. But, we don't want to do that for a while, as we want to keep its Pages site up to redirect to the new location of Storybook.

Until then, in order to discourage the creation of new issues and merge requests, we'll update the default templates to refer people to the design.gitlab.com project instead.

What about GitLab UI's commit history, blame views, etc?

The commit history of GitLab UI's main branch will be copied over in its entirety. That means that all the usual history tools, like git log, git blame, and their counterparts in GitLab's interface, will all just work in the design.gitlab.com repository/project.

What about Renovate bot dependency updates?

For upgrades of the @gitlab/ui project in other projects, like GitLab, these will continue to happen just as they do now.

For upgrades to dependency updates within GitLab UI, these will also continue as they do now, but will of course be done in the design.gitlab.com project.

What about the `#gitlab-ui` Slack channel?

We have no plans to change it. If you have thoughts about this, please share them!

Will maintainer roles be transferred over?

Yes. If you're a maintainer of GitLab UI, you'll become a maintainer of design.gitlab.com.

We will likely lean more on Code Owners to ensure the right people review each merge request.

If you'd rather not be a maintainer of the design.gitlab.com project, let us know. In any case, it's a two way door decision!

What about GitLab Roulette?

We will update GitLab Roulette to reflect these changes. This likely means removal of the "gitlab-ui" project from the dropdown, in favour of the existing "design.gitlab.com" project.

We will make corresponding changes to team.yml as part of this.

Why merge GitLab UI into design.gitlab.com and not the other way around?

We are merging GitLab UI into design.gitlab.com because the design.gitlab.com project represents the totality of the design system. We'll likely eventually merge other projects in as well, like GitLab SVGs, GitLab Fonts, etc. So design.gitlab.com is the most central, logical place to house all of that, whereas the GitLab UI project is not.

When will this happen?

It's already happening! The basic merge was done in !4450 (merged).

As of 2025-05-28, work is ongoing to fix problems and document the changes.

References

Edited May 28, 2025 by Mark Florian