GitLab UI

GitLab UI is a UI component library that implements Pajamas, our
design system. GitLab UI is written in Vue.js and its objectives are to:

- Create reusable UI components to accelerate frontend development.
- Create UI consistency for all components within GitLab.

See for documentation.

Usage

1. To use GitLab UI in your project, add it as a dependency:

``sh
yarn add @gitlab/ui
`

> Note: Make sure to also install GitLab UI's peer dependencies. Refer to the
> package.json for the list of peer dependencies and their expected versions.

1. In your main entrypoint before importing or using any component:

`javascript
import setConfigs from '@gitlab/ui/dist/config'

setConfigs()
`

This will set the global configs used by GitLab UI.

1. Include the required stylesheets in your app. Refer to the CSS docs for
installation options.

1. Import the components as desired:

`javascript
import { GlButton } from '@gitlab/ui';
`

> Note: GitLab UI is compatible with tree-shaking, you may enable this in your project to
> reduce bundle sizes.

Quick start - development

Note: GitLab UI isn't designed to be built on Windows natively. Either
WSL or
GitPod can be used to set up a
UNIX-like environment in which to build it.

Make sure you have Node 16.x (LTS) and Yarn 1.22
or newer.

`sh


Clone the project

git clone git@gitlab.com:gitlab-org/gitlab-services/design.gitlab.com.git

Navigate to the root of the project

cd design.gitlab.com/packages/gitlab-ui

Install all the dependencies of the project

yarn # or yarn install

Build and launch storybook to see the components in the browser

yarn storybook
`

Go to

Testing

$3

Components’ unit tests live in the tests/components. The tests are organized following the same
directory structure used to organize components.

- yarn test:unit runs all unit tests.

- yarn test:unit:watch runs all unit tests in watch mode.

- yarn test:unit:debug runs all unit tests and allow to attach a debugger to the test runner process.

- yarn jest [name_pattern] runs spec files that match the specified name pattern.

#### Examples

- yarn jest datepicker will match all spec files with a name that contains the word _datepicker_.

- yarn jest datepicker -t "when draw event is emitted" goes a step further and only runs the test
with a description that matches the argument passed to the t flag.

$3

Even though we try to avoid writing complex SASS code to maintain CSS complexity low, we’ve
implemented some functions that benefit from automated testing. SASS tests live in the tests/scss
directory. GitLab UI uses sass-true to implement these tests, and
jest run them.

yarn jest run_scss_tests runs all SCSS tests.

$3

GitLab UI uses visual snapshot tests to prevent introducing regressions with CSS and
layout changes on components. Read more on this in the visual testing documentation.

#### GitLab visual regression tests

GitLab UI components are a reference implementation of the
Pajamas Design System components. These components
should conform with the design system specs, and they should look correct in the pajamas website and
the GitLab product. Please see Debugging GitLab UI issues with GitLab product CSS
for information on how to debug issues with GitLab product CSS in GitLab UI.

$3

Components’ end to end tests live in the cypress/e2e folder. See our
end to end testing documentation for more details.

yarn run cypress open runs Cypress locally to run end to end tests.

$3

GitLab UI uses design tokens to maintain a single source of truth that, through automation,
can be formatted for different uses. Read more on this in the design tokens documentation.

Releases

See Updating GitLab UI Packages for information on how the
@gitlab/ui` package is kept up to date in various projects.

To publish new versions of GitLab UI, see publishing packages.

Contributing guide

Please review the design system contribution process
for an overview of how to contribute to Pajamas.

For GitLab UI–specific details, refer to Contributing to GitLab UI for
additional resources and guides.

$3

Any question? Have a look at our FAQ.md, you might find the answer there.