Develop

Prerequisites

Before you begin, install:

NOTE: yarn@2 and later are not currently supported.

Creating a new project

Create a new project using @gitlab/ui by running:

yarn create @gitlab/ui

That command will ask some questions, create the project, and tell you how to run it.

Alternatively, skip the questions by answering them directly:

yarn create @gitlab/ui --vue-version=compat ~/Projects/my-new-app

What's included

When you create a new project, the starter scaffolds a ready-to-run application with the following dependencies and configuration pre-installed:

  • @gitlab/ui - GitLab's UI components
  • @gitlab/svgs - GitLab's SVG icons and illustrations
  • @gitlab/fonts - GitLab's typography and font assets
  • .gitlab-ci.yml - CI/CD pre-configured for automatic deployment to GitLab Pages
  • tailwind.config.js - Tailwind configuration powered by Pajamas design tokens, and supports dark mode
  • vite.config.js - Vite development server config
  • vue/@vue/compat - Application framework
  • vue-router - Routing library

The generated project structure looks like this:

my-gitlab-ui-app/
├── src/
│   ├── assets/         # Static assets
│   │   └── favicon.svg
│   ├── components/     # Application chrome components
│   │   ├── app_header.vue
│   │   ├── app_panel.vue
│   │   ├── app_rail.vue
│   │   └── app_sidebar.vue
│   ├── data/           # Mock data for the application chrome
│   │   ├── breadcrumbs.json
│   │   └── navigation.json
│   ├── layouts/        # Layout components
│   │   └── default_layout.vue
│   ├── router/         # Routing
│   │   └── index.js
│   ├── styles/         # Styles
│   │   └── _fonts.scss
│   ├── views/          # Application views
│   │   └── home_view.vue
│   ├── app.vue         # Root component
│   ├── compat.js       # @vue/compat configuration
│   └── main.js         # Application entry point
├── .gitignore
├── .gitlab-ci.yml      # GitLab Pages deployment
├── .prettierrc
├── index.html          # HTML entry point
├── package.json
├── README.md
├── tailwind.config.js  # Tailwind with Pajamas design tokens
└── vite.config.js      # Vite development server config

Vue version

The starter uses Vue 3 (@vue/compat) by default, and this page documents that configuration. Vue 2 is also supported.

Run yarn create @gitlab/ui --help for more information.

Creating views

Create a new view by adding a Vue component in src/views/. For example, create src/views/my_view.vue:

<script>
import { GlCard } from '@gitlab/ui';

export default {
  name: 'MyView',
  components: { GlCard },
};
</script>

<template>
  <div>
    <gl-card>
      <template #header>My prototype</template>
      <p>Add your content here</p>
    </gl-card>
  </div>
</template>

Adding routes

In src/router/index.js, add your view to the routes array with:

  • path: URL path (e.g., '/my-view')
  • name: Unique identifier for the route
  • component: The Vue component to display
  • meta.title: Page title (shown in navigation and browser tab)
{
  path: '/my-view',
  name: 'my-view',
  component: () => import('../views/my_view.vue'),
  meta: {
    title: 'My view',
  }
}

Application chrome

Your views render inside a mock GitLab application chrome, so prototypes feel like they live in the product without you having to build the surrounding UI. It is defined in src/layouts/default_layout.vue and made up of three components in src/components/:

  • app_header.vue - the top bar with the logo, breadcrumbs, search, and user controls
  • app_sidebar.vue - the collapsible "Your work" navigation
  • app_rail.vue - the right-hand rail with GitLab Duo actions and the dark mode toggle

The header and sidebar are driven by mock data in src/data/. Edit breadcrumbs.json to change the breadcrumb trail and navigation.json to change the sidebar navigation items. To customize the chrome itself, edit the components directly—or remove them from default_layout.vue if you want a blank canvas.

Using Pajamas components

Import components from @gitlab/ui and register them in the components option:

<script>
import { GlButton } from '@gitlab/ui';

export default {
  components: { GlButton },
};
</script>

All Pajamas components use the Gl prefix. In templates, use kebab-case:

<template>
  <gl-button variant="confirm" @click="handleAction">
    Confirm
  </gl-button>
</template>

Finding props and variants

Each component page in Components documents available props, variants, and usage guidelines. The Storybook provides interactive controls for props so you can preview each value before writing code. Unsupported prop values log a warning in the browser console.

Applying styles

Prefer component props over utility classes, and utility classes over custom CSS:

<!-- Best: semantic prop -->
<gl-icon variant="danger" />
<!-- Acceptable: utility class -->
<gl-icon class="gl-text-danger" />
<!-- Avoid: custom class -->
<gl-icon class="some-custom-class-styles" />

Component props encode design intent and adapt automatically to color modes. Utility classes stay aligned with design tokens. Custom classes bypass both systems and risk visual drift.

Styling with GitLab-configured Tailwind utilities

Pajamas provides a Tailwind CSS configuration powered by design tokens. Utility classes are prefixed with gl-, ensure consistency with the GitLab product, and support dark mode out of the box.

<div class="gl-border gl-flex gl-gap-4 gl-rounded-base gl-bg-default gl-p-3">
  <p class="gl-mb-0 gl-text-subtle">Styled with GitLab-configured Tailwind</p>
</div>

Utilities reference design token CSS custom properties for their values. Use them as classes or via @apply rules for general styling and component customization.

Deploying to GitLab Pages

The starter includes a .gitlab-ci.yml configuration file that automatically builds and deploys your prototype to GitLab Pages.

  1. Push your changes to the main branch.
  2. GitLab CI/CD builds your project and deploys it to Pages.
  3. Your project is available at https://<namespace>.gitlab.io/<project-name>/

No additional configuration needed—just push to main and your project goes live!

Resources

Last updated at: