pajamas

GitLab Pajamas — design system operations

Research snapshot: 2026-07-30. This file records publicly documented operating practices and does not recommend a model for another system.

1. Governance

• GitLab’s Design System team maintains and evolves Pajamas with contributors. Pajamas is divided into a core layer, directly owned by the Design System team, and an extended layer, owned by the teams that create the contribution. Contributing
• Core contains broadly used foundations, components, patterns, and guidance where consistency, accessibility, and long-term stability are prioritized. Extended contains production-ready, reusable work that can benefit more than one place without needing system-wide adoption. An extended item can later graduate to core after demonstrating cross-domain value and stability. Design system philosophy
• The Design System team classifies proposed work as core, extended, or out of scope and assigns a support level: no support, consult and review, task-specific, or end-to-end. Core changes require Design System team review and approval and receive a team point of contact; the default support level is consult and review. Extended work defaults to no support and remains contributor/team-owned. Contributing
• After required approvals, the owner of the layer or element can merge the change. Significant changes are to be shared with the wider UX and engineering groups. Contributing

2. Component lifecycle

• Pajamas currently documents a flexible contribution lifecycle of Define → Design → Build → Document. Define makes the need and rationale visible; Design creates or updates UI Kit assets; Build implements the change with functional parity and tests; Document adds guidance, examples, and references. Stages can overlap, occur in a different order, or be skipped for narrowly scoped changes. Contribution lifecycle
• A proposal belongs in Pajamas when it represents more than a one-off use case, cannot be met by an existing element, has evidence of reuse, and is feasible to maintain. Many new components and patterns start in the extended layer rather than entering core directly. Contribution lifecycle
• The public lifecycle is not a proposed/draft/beta/stable state machine. Readiness is instead evaluated across design, code, documentation, and accessibility. For core components, design checks cover states, variants, Figma publication, and parity with code; code checks cover functionality, controls/props, tests, and parity with design; docs are ready when they have no TODOs, include examples, and provide comprehensive configuration detail; accessibility is evaluated after code is ready. Component health evaluation tracking
• Integration into the GitLab product is treated separately from contribution completeness. Components can be partially integrated, and complex migrations are expected to have a migration plan coordinated with the Design System team. The lifecycle documentation discourages creating parallel New components without an agreed migration path because this created choice confusion and technical debt in the past. Contribution lifecycle
• Deprecation is represented in component guidance and issue tracking. For example, the health evaluation identifies components that should no longer be used and tracks follow-up removal work rather than treating deprecation as an automatic lifecycle transition. Component health evaluation tracking

3. Contribution process

• Work begins by searching the issue tracker and creating an issue or merge request; issues are preferred, while clearly scoped changes can begin as a merge request. The formal process begins when the work is visible in GitLab. Contributing
• The Design System team classifies the contribution and assigns its support level. Core criteria include broad multi-domain use, no clear domain owner, system-wide consistency risk, maturity and stability, full accessibility conformance, and the presence of design specs, Figma assets, code, and documentation. Extended criteria allow evolving, domain-owned work used in more than one place and require code and documentation, with Figma assets optional. Contributing
• Every contribution should consider design, code, and documentation together to prevent parity gaps. The contribution may start in any of those surfaces, but it is expected to be made visible early and aligned before merge. Contributing, Contribution lifecycle
• GitLab team members with paid Figma organization access use a Figma update issue template and request branch review from a Figma maintainer. The review description generates release notes and begins with one of: Adds, Enhances, Changes, Removes, Fixes, Deprecates. External contributors cannot edit the internal UI Kit directly; they can submit issues, concepts, screenshots, documentation, code, and accessibility improvements, with a GitLab team member completing any required internal Figma work. UI Kit contributing
• Repository merge requests create review apps for inspecting documentation changes. The repository also applies automated linting and tests to code changes. Pajamas repository README

4. Versioning and release cadence

• Pajamas and GitLab UI now share a unified repository, and package releases use Changesets to generate version changes and changelogs. This replaced the repository’s earlier semantic-commit release workflow. Unified repository feedback issue
• Public GitLab releases use semantic package versions and categorize release notes as major, minor, or patch changes. The releases page shows multiple patch releases when changes are ready rather than a stated calendar cadence. Pajamas releases
• A GitLab UI code change is not visible in the Pajamas documentation site until the package used by the site is updated. Contribution lifecycle
• Figma branch review descriptions are used to generate UI Kit release notes, using standardized action verbs for additions, enhancements, changes, removals, fixes, and deprecations. UI Kit contributing
• No fixed public weekly, monthly, or milestone release cadence is specified in the cited Pajamas operating documentation.

5. Documentation structure and templates

• The unified component page combines design guidance and developer documentation. Typical pages include: a definition; live examples; a numbered structure/anatomy diagram; guidelines such as when to use, when not to use, variants, behavior, and content; accessibility guidance; related terminology or references; and code reference material with imports, props, defaults, and implementation notes. Badge, Checkbox
• Component pages link to the Pajamas UI Kit and automatically surface issues and merge requests through a component: label. When the page name and label differ, frontmatter can specify componentLabel. Pajamas repository README
• Documentation health requires a page for every component, no unresolved TODOs, examples, and comprehensive configuration details. Component health evaluation tracking
• Documentation images use a figure-img wrapper with a caption/text equivalent; SVG images require appropriate role and label treatment. Pajamas repository README

6. Naming and token conventions

• Design tokens are grouped as constant, semantic, or contextual. Constants are base values and are not intended for direct use; semantic tokens encode global intent; contextual tokens encode a component, pattern, or experimental context. Design tokens overview
• Pajamas uses a structured token naming model: [group].[component].[variant/category].[element].[position].[relationship].[property].[type].[scale].[state]. Names include only the specificity needed, start with context when applicable, and include an object in semantic and contextual token names. Authoring design tokens
• Tokens are authored in *.token.json files following the Design Tokens Community Group format with $value and $type. Generated names use a gl namespace: CSS --gl-*, Sass $gl-*, and uppercase JavaScript constants. Authoring design tokens
• Token terminology distinguishes context, object, and modifier. States such as hover or checked appear late in the name; finite ordinal scales use terms such as subtle, strong, sm, md, and lg. Reading design tokens
• GitLab issue labels for components use a component: prefix, with grouped names where needed, such as component:form-checkbox. Pajamas repository README

7. Accessibility criteria and enforcement

• Pajamas states that it satisfies WCAG AA for normal text. Its color guidance documents the 4.5:1 ratio for normal text, 3:1 for large text, and the rule that color cannot be the sole means of communicating information. Color
• Merge request reviewers are asked to check keyboard operation, visible focus, text alternatives, screen-reader announcements for state changes, and sufficient color contrast. Accessibility best practices
• Pajamas explicitly notes that automated tools find only some accessibility issues and that manual testing remains necessary. Its evaluation guides cover visual review, content and semantics, keyboard-only use, and screen readers. Accessibility evaluation overview
• Component-specific accessibility requirements live on component pages alongside the implementation reference. Badge, Checkbox
• In the component health process, accessibility evaluation starts only after code is ready. A passing evaluation is marked Tested; untested or known-problem components are Incomplete and open issues are tracked with component and accessibility labels. Component health evaluation tracking

8. Audit and review cycle

• Pajamas has a component health evaluation that reviews core components across design, code, documentation, and accessibility and records findings, open work, parity gaps, and deprecation recommendations in a matrix. Extended components are excluded from the cited core evaluation. Component health evaluation tracking
• The health criteria explicitly compare Figma assets with code examples in both directions and require a documentation page without TODOs. Accessibility is re-evaluated after code readiness, and findings create or update component/accessibility issues and epics. Component health evaluation tracking
• The contribution lifecycle requires parity among design, code, and documentation for each change; complex components require migration planning to avoid parallel versions and unresolved integration debt. Contribution lifecycle
• Public documentation does not specify a fixed recurring interval for the component health audit. The cited tracking issue shows an active evaluation program and dated findings, not a calendar policy.