| name | pajamas |
| description | GitLab Pajamas Design System expert for building UIs with Pajamas components and patterns. Use when: (1) implementing UI that should follow GitLab's Pajamas design system, (2) selecting or configuring Pajamas/GlComponent components (GlButton, GlAlert, GlModal, etc.), (3) translating Figma designs into Pajamas-compliant code, (4) questions about Pajamas component usage, variants, categories, or accessibility, (5) building GitLab-style interfaces, or (6) the user mentions "Pajamas", "GitLab UI", "Gl components", or "design system" in a GitLab context. Works hand-in-hand with the implement-design skill and Figma MCP tools.
|
Pajamas Design System
Provides expertise for implementing UIs using GitLab's Pajamas Design System, drawing from the single source of truth (SSoT) documentation and design token definitions bundled in this skill.
INITIALIZATION — Run Before Anything Else
Before answering any question or performing any task, check whether the local reference files exist. If the references/pajamas-docs/ directory is missing or empty, you MUST populate it by running the following commands from this skills directory:
bash scripts/update-refs.sh
python3 scripts/build-index.py
python3 scripts/build-token-map.py
These scripts clone the upstream Pajamas repository, extract docs and design tokens into references/, and build the component index and token map. The references/ directory is gitignored — it is always populated locally via these scripts.
Do not skip this step. The reference files are required for all component lookups, token resolution, and design guidance below.
Project Scaffold — Check Peer Dependencies First
Before creating or scaffolding a new project, always check the peerDependencies of @gitlab/ui to determine compatible framework versions. Then pick a project scaffold that satisfies those constraints.
- Read
peerDependencies: Run npm info @gitlab/ui peerDependencies --json (or inspect the package.json in the installed package) to discover required Vue version, etc.
- Pick a compatible scaffold: Choose a project template / generator that matches the required Vue version and build toolchain. For example, if
@gitlab/ui requires vue@^2.7, do not scaffold a Vue 3 / Vite project — use a Vue 2.7-compatible setup instead.
- Verify after install: After scaffolding, confirm there are no
ERESOLVE or peer-dependency warnings. Resolve any conflicts before writing component code.
CRITICAL RULE: Always Use Design Tokens — NEVER Use Absolute Values
NEVER write absolute/hardcoded values for colors, spacing, typography, borders, shadows, or any visual property. Always use Pajamas design tokens instead.
This applies to ALL output — CSS, SCSS, HTML attributes, inline styles, utility classes. No exceptions.
- NEVER write
color: #1f75cb — use var(--gl-color-blue-500) or a semantic token
- NEVER write
padding: 16px — use a spacing token via utility class or CSS variable
- NEVER write
font-size: 14px — use var(--gl-font-size-200) or equivalent
- NEVER write
border-radius: 4px — use var(--gl-border-radius-base) or equivalent
- NEVER write
background: white or color: black — use var(--gl-background-color-default) and var(--gl-text-color-default)
When encountering absolute values
When you see an absolute value in a Figma design, existing code, or user request:
- Search the token map: Read references/design-tokens/token-map.md and search for the exact value
- If exact match found: Use that token
- If no exact match: Find the closest value in the same category (e.g., closest color in the same hue, closest spacing value) and use that token
- Prefer semantic over constant tokens: Use
--gl-text-color-subtle (semantic) over --gl-color-neutral-500 (constant) — semantic tokens adapt across color modes (dark mode, high contrast)
Token usage priority (in order of preference)
- Pajamas components — use
GlButton, GlAlert, etc. which apply tokens automatically
- CSS utility classes —
gl-bg-subtle, gl-text-default, gl-p-3, gl-rounded-base
- CSS custom properties —
var(--gl-background-color-default) when utilities don't cover the case
- NEVER raw values — no hex codes, no pixel values, no named colors
Token reference files
SSoT References
The authoritative Pajamas docs live at references/pajamas-docs/ within this skill, mirroring the contents/ directory of the upstream repo. Design token definitions live at references/design-tokens/. These files are not committed to git — they are populated locally by running the initialization scripts (see above).
- Upstream:
git@gitlab.com:gitlab-org/gitlab-services/design.gitlab.com.git (branch: main)
- Docs:
contents/
- Tokens:
packages/gitlab-ui/src/tokens/
- Populate / update: Run
bash scripts/update-refs.sh then python3 scripts/build-index.py && python3 scripts/build-token-map.py
Component Lookup Workflow
- Consult the index: Read references/component-index.md to find the relevant component, pattern, or foundation by name
- Read the SSoT doc: Load the full doc from
references/pajamas-docs/{reference_file} (e.g., references/pajamas-docs/components/button.md) for detailed usage, variants, props, examples, and accessibility guidance
- Check related components: Each doc's YAML frontmatter includes a
related: list — review related components when choosing between alternatives
- Resolve tokens: For every visual property, look up the correct design token in references/design-tokens/token-map.md — never output an absolute value
When searching for a component by function rather than name, grep the component-index.md descriptions or search the references/pajamas-docs/ directory.
CRITICAL RULE: Use Real Components — NEVER Reimplement With Raw HTML/CSS
If a Code Connect mapping exists for a Figma node, you MUST use that component. Do not reimplement it with raw HTML/CSS.
When matching a Figma element to a Pajamas component, follow this lookup chain in order:
- Code Connect mapping — If the Figma node has a Code Connect mapping to a
@gitlab/ui component, use it. This is authoritative; no further lookup needed.
- Layer names — Inspect the Figma layer names. If a layer is named after a known component (e.g., "GlButton", "Button", "Avatar"), use the corresponding
@gitlab/ui component.
- Component source — If layer names are generic, look at the source component in Figma (the main component the instance derives from) to identify the design-system component.
- Description match — If the source is unclear, search references/component-index.md for the component whose description most closely matches the visual element and behavior.
- Ask the user — If none of the above produce a confident match, ask the user to confirm which component they are using, or whether this is a non-component (custom UI that has no Pajamas equivalent).
Only after exhausting all five steps may you fall back to custom HTML/CSS — and even then, you must use Pajamas design tokens (never absolute values).
Integration with Figma and implement-design
This skill complements the implement-design skill. When implementing a Figma design for a GitLab project:
- implement-design fetches design context and screenshots from Figma
- This skill maps the Figma output to the correct Pajamas components and design tokens
- Together they produce pixel-perfect, design-system-compliant code
During Step 5 (Translate to Project Conventions) of the implement-design workflow:
- Identify Pajamas components that match each Figma element
- Look up the SSoT doc for each component to get correct props, variants, and categories
- Replace every absolute value from Figma (hex colors, px sizes, font specs) with the corresponding Pajamas design token — consult token-map.md for reverse lookups
- Follow Pajamas patterns for form layouts, navigation, feedback, etc.
Key Pajamas Conventions
Component import reference
The GitLab Pajamas component library is published as @gitlab/ui. It requires Vue 2.7.
Key components (non-exhaustive):
| Import | Purpose |
|---|
GlButton | Actions and navigation triggers |
GlCheckbox | Boolean form input |
GlAvatar | User / project identity |
GlSearchBoxByType | Inline search-as-you-type |
GlBreadcrumb | Hierarchical navigation |
GlAlert | System feedback messages |
GlModal | Confirmation / dialog overlays |
GlDrawer | Contextual side panel |
GlTabs | Tabbed content areas |
GlTable | Data rows and columns |
GlToggle | On/off switches |
GlBadge | Status metadata |
GlLabel | Categorization |
GlLink | Navigation to URL |
All imports come from @gitlab/ui:
import { GlButton, GlCheckbox, GlAvatar } from '@gitlab/ui';
For the full catalog see references/component-index.md.
Component naming
- Vue components:
Gl prefix — GlButton, GlAlert, GlModal, GlDrawer
- HTML tags (in templates):
<gl-button>, <gl-alert>, <gl-modal>
- Ruby/HAML:
Pajamas::ComponentName — Pajamas::ButtonComponent
Common component API patterns
- category:
primary, secondary, tertiary (visual prominence)
- variant:
default, confirm, danger (semantic intent), or info, warning, success, danger (feedback)
- size:
small, medium (default)
- block: Boolean, makes component full-width
- disabled, loading, selected: State booleans
Utility classes
Pajamas uses gl- prefixed utility classes (e.g., gl-mt-3, gl-mb-5, gl-flex). These map to Pajamas design tokens for spacing, color, and layout. Always use these instead of raw Tailwind or custom CSS.
Using color scale values directly like .gl-text-green-900 or .gl-bg-white is deprecated. Use semantic utilities: .gl-text-subtle, .gl-bg-default.
Component Selection Guide
When deciding which component to use:
| Need | Component | SSoT Reference |
|---|
| Trigger an action | GlButton | components/button.md |
| System feedback message | GlAlert | components/alert.md |
| Temporary notification | GlToast | components/toast.md |
| Confirm destructive action | GlModal | components/modal.md |
| Contextual side panel | GlDrawer | components/drawer.md |
| Boolean input | GlCheckbox | components/checkbox.md |
| Single choice from group | Radio button | components/radio-button.md |
| Text entry | GlFormInput / GlTextarea | components/text-input.md |
| Select from list | GlCombobox | components/dropdown-combobox.md |
| Menu of actions | Disclosure | components/dropdown-disclosure.md |
| Tabbed content | GlTabs | components/tabs.md |
| Data in rows/columns | GlTable | components/table.md |
| Show/hide content | GlAccordion / GlCollapse | components/accordion.md |
| Navigate hierarchy | GlBreadcrumb | components/breadcrumb.md |
| Page-level navigation | Pagination | components/pagination.md |
| User identity | GlAvatar | components/avatar.md |
| Status metadata | GlBadge | components/badge.md |
| Additional info on hover | GlTooltip / GlPopover | components/tooltip.md |
| Loading state | GlSkeletonLoader / GlSpinner | components/skeleton-loader.md |
| Date selection | Date picker | components/date-picker.md |
| Categorize objects | GlLabel | components/label.md |
| Navigate to URL | GlLink | components/link.md |
| Process steps | GlPath / Stepper | components/path.md |
| On/off toggle | GlToggle | components/toggle.md |
| Search | Search component | components/search.md |
| Filter content | Filter | components/filter.md |
| Segmented options | Segmented control | components/segmented-control.md |
SSoT references in the table above are relative to references/pajamas-docs/. For the full catalog, see references/component-index.md.
Patterns
Pajamas defines higher-level interaction patterns. Always check the relevant pattern doc when implementing:
| Pattern | When to reference | SSoT Reference |
|---|
| Forms | Any form layout | patterns/forms.md |
| Empty states | No-data views | patterns/empty-states.md |
| Loading | Async content | patterns/loading.md |
| Saving & feedback | After mutations | patterns/saving-and-feedback.md |
| Destructive actions | Delete/remove flows | patterns/destructive-actions.md |
| Navigation sidebar | App navigation | patterns/navigation-sidebar.md |
| Notifications | System alerts | patterns/notifications.md |
| Filtering | List/table filters | patterns/filtering.md |
| Search | Search UX | patterns/search.md |
| Feature discovery | New feature callouts | patterns/feature-discovery.md |
| AI interactions | Duo/AI features | patterns/duo-chat.md |
SSoT references above are relative to references/pajamas-docs/.
Accessibility
Every Pajamas implementation must meet WCAG AA. Key rules:
- Always provide
aria-label on icon-only buttons
- Ensure sufficient color contrast (check with foundation docs)
- Support keyboard navigation for all interactive elements
- Use semantic HTML elements
- Read
references/pajamas-docs/accessibility/a11y.md for comprehensive guidelines
Updating References
Pull the latest docs and token definitions from upstream, then regenerate indexes:
bash scripts/update-refs.sh
python3 scripts/build-index.py
python3 scripts/build-token-map.py
