Restructure repositories related to the design system
Background
Pajamas, the design system behind GitLab is getting better every day and the impact it has directly on the implementation of product features is already tangible. However, let's talk about metrics, roadmap, and how to improve UX/FE collaboration in another issue.
Problem
Here are some problems that I think are holding back lift-off and how we can improve this and lay a foundation for the future. The following has already taken into account dogfooding antipatterns. For example, the design system is not built outside of GitLab, but already builds GitLab itself.
- Repositories that are currently related to the design system are scattered across the
gitlab-org
group. Seedesign.gitlab.com
,gitlab-ui
, andgilab-svgs
. This got worse due to the recent move ofdesign.gitlab.com
to the subgroupgitlab-services
in #96 (closed) to dogfood Auto DevOps.- Problem: This subtly lessens the strength of the design system and makes it harder to grasp what is, or eventually should be, part of the design system. Also, contributing to scattered repositories to push forward a design system feels unfulfilling and disorganized, as also mentioned by GitLab team members.
- The
gitlab-svgs
is hosting both icons and illustrations which was initially configured that way to allow faster iteration.- Problem: This has made illustrations a second class citizens and illustrations are currently suffering from structural differences, vary in size, and more which is reflected in implemented components like empty states (see #115 (comment 105509332)) and more. See also #228 (closed). Also, contributing to illustrations feels also unfulfilling and makes it easier to invest less time and care less about illustrations themselves.
- The component updates in
gitlab-ui
repository often do not receive considerable attention by the UX team members which makes component documentation out of date indesign.gitlab.com
. For example, see !458 (merged). - The component updates in
design.gitlab.com
repository often do not receive considerable attention by the FE team members which makes component documentation out of date ingitlab-ui
. For example, see gitlab-org/gitlab-ui#235 (closed).
Proposal
Let's make some small corrective changes that could help improve the problems mentioned above and lay a solid foundation for the future. I'd suggest to start with Stage 1A and pick 2A or 2B to move forward.
Stage 1A
- Let's bring together all the repositories related to the design system under a single group named pajamas. It's ok to host this under the
gitlab-org
group or move this to a separate top-level group.- Benefit: Having a single group to host all repositories related to the design system will make it easier to locate all repositories related to the design system. This could also make UX and FE team members have a more satisfying contribution experience and slightly improve the contribution quality when contributing to any of these repositories.
Stage 2A
- Includes steps in stage 1A.
- Rename
design.gitlab.com
todesign-gitlab-com
. See #354 (closed).
Stage 2B
- Includes steps in stage 1A.
- Rename
gitlab-ui
repository topajamas-components
. - Rename
design.gitlab.com
repository topajamas-docs
. - Split
gitlab-svgs
into two separate repositories, one for hosting icons and one for illustrations. Replicating the previewer alongside as is also sounds good to avoid adding any extra overhead at the moment. - Rename the repository related to icons to
pajamas-icons
- Rename the repository related to illustrations to
pajamas-illustrations
- Update corresponding package repositories in npm. The
gitlab-ui
package has been moved in the past, too. See@gitlab-org/gitlab-ui
v.@gitlab/ui
. - Optionally, this could introduce a new top-level package organization
@pajamas
but using@gitlab
is also ok. If this sounds ok, renaming@gitlab/ui
to@gitlab/components
and splitting@gitlab/svgs
to@gitlab/icons
and@gitlab/illustrations
sounds optimal.
Other benefits
- New relevant repositories can emerge or branch off the current repositories to allow better developer scalability and autonomicity as the team grows. For example, separating the charts component into a separate repository could be beneficial in the future.
- Teams can experiment and try out new technology stacks or even improve the current stacks (see Nuxt.js) which is currently used for the
design.gitlab.com
and the previewer ingitlab-svgs
. - This subgoup can also utilize Auto DevOps and continue using Auto DevOps for
pajamas-docs
. Most probably the two new repositories (pajamas-icons
andpajamas-illustrations
) will be also able to utilize Auto DevOps.