Develop

Prerequisites

Before you begin, install:

• Node.js
• Yarn (v1 Classic)

Creating a new project

To create a new project using @gitlab/ui, run:

yarn create @gitlab/ui my-gitlab-ui-app
cd my-gitlab-ui-app
yarn install
yarn start

Replace my-gitlab-ui-app with your desired project name.

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 - Application framework
• vue-router - Routing library

The generated project structure looks like this:

my-gitlab-ui-app/
├── src/
│   ├── assets/         # Static assets
│   │   └── favicon.svg
│   ├── layouts/        # Layout components
│   │   └── default_layout.vue
│   ├── router/         # Routing
│   │   └── index.js
│   ├── styles/         # Styles
│   │   └── _fonts.scss
│   ├── views/          # Application views
│   │   └── home_view.vue
│   ├── app.vue         # Root component
│   └── 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

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',
  }
}

Styling with GitLab-configured Tailwind utilities

The starter includes a Tailwind CSS configuration powered by Pajamas design tokens. These are GitLab-configured utility classes (prefixed with gl-) that 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>

For a complete list of available utilities, see the Tailwind documentation. For a quick reference of colors, sizes, and other design token values, see Tailwind utilities.

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!

Using Pajamas components

You can import and use any Pajamas component directly in your views:

import { GlButton, GlCard, GlAlert } from '@gitlab/ui';

Refer to the Components section of Pajamas for detailed documentation on available components and their usage.

Resources

• Components Storybook
• Icon directory
• Tailwind utilities