Skip to content

Update contribution pages on design.gitlab.com

Note: this content is intended to replace the contribution page at design.gitlab.com

Contributing

Contributing to Pajamas keeps GitLab’s design system healthy and effective. Every contribution, large or small, helps teams move faster, deliver a cohesive experience, and reduce duplicate effort.

The Design System team maintains and evolves Pajamas in partnership with contributors. Our goal is to make contributing straightforward and collaborative. Proposals should feel welcome, and contributors can expect constructive, timely feedback. If you have suggestions for improving the process, please share them [link to feedback issue].

Contributions can start in design, code, or both. However they begin, what matters is making the work visible early, opening it up for feedback, and aligning before it is merged. To guide this work, Pajamas is organized into two layers:

  • The Core layer represents the shared building blocks of Gitlab’s product. It includes widely used foundational elements, components, patterns, and guidelines directly owned by the Design system team.
  • The Extended layer provides space for reusable components and patterns that are valuable in more than one place,even if they don’t need to  scale across the entire product. Extended contributions are owned by the teams who create them.

Both layers depend on active contributions, and we encourage proposals of any size or scope. 

[Describe how people can recognize elements in the core and extended layer on design.gitlab.com].

Contribution process

The contribution process provides structure for moving work from idea to adoption. Contributions may be new components, changes to existing ones, open questions, design explorations, or bug reports. The first step is always classification into the core or extended layer, confirmed by the Design System team. 

1. Create an issue or open a merge request

Start by ensuring that an issue or merge request exists. Search the issue tracker for related work before creating a new one. While discussion can happen in many places, the formal process begins once the work is in GitLab. We prefer to start with an issue, though clearly scoped updates can also begin as a merge request.

2. Classify as core or extended

After you open an issue or merge request, the Design System team will classify the contribution as core, extended, or out of scope for the design system. If you are discussing or modifying an existing element, we will continue to use its current classification.

Core layer criteria

Extended layer criteria
  • Used broadly across multiple domains and teams
  • Not clearly owned by a single domain team.
  • Establishes the system-wide standard for consistency
  • Built on mature and stable design and implementation
  • Risky if implemented inconsistently
  • Fully conforms to accessibility standards.
  • Supports current and future needs of teams.
  • Must include design specs, Figma assets, code assets, and documentation
  • Reusable in more than one place, but not necessarily across multiple domains.
  • May be primarily domain-owned, but valuable to share across teams.
  • Can represent early-stage or evolving components and patterns
  • Solves current needs without needing to scale across the entire product
  • Should include documentation and code (Figma assets and design specs optional)

3. Define level of support

To guide contributors, the Design System team will identify an an initial level of support:

  • No support: the contributor owns execution with no involvement from the Design System team.
  • Consult and review: the contributor leads execution while the Design System team provides feedback, advice, and review.
  • Task-specific: the Design system team takes responsibility for a specific part of the process and provides feedback and/or deliverables (for example, producing UI kit assets or writing documentation)
  • End-to-end: the Design System team leads execution through completion, working closely with the contributor and providing feedback, guidance, and review at every stage of the process.

Supporting contributions to the core layer

Any changes to the core layer require review and approval from members of the Design System team. When a contribution is classified as core, a point of contact will be assigned to work with you. This person is available to guide you through the process, help ensure changes align with guidelines and system-wide quality, and prepare the work for long-term ownership and maintenance by the Design System team. 

Default support level: Consult and review. If a higher level of support is requested, it will be triaged and, if accepted, incorporated into milestone planning.

Contributing to the extended layer

Extended items are generally owned by the team that created them, though in some cases they may be owned by a broader group of maintainers. When a contribution is classified as extended, the Design System team will check in to understand what support, if any, you need. You can also reference the reviewer list or proposal template to find who to engage. As the contributor, it is your responsibility to move the work forward, with optional guidance available from the Design System team.

Default support level: No support. If a higher level of support is requested, it will be triaged and, if accepted, incorporated into milestone planning.

4. Merge your changes

After the necessary approvals, the respective owner of the layer or element can merge the change. If there are any significant changes, please share the with the wider UX and Engineering groups.

Code of conduct

[Code of conduct included here]

Edited by Chris Micek