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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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:
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:
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
Usage guide: components vs. utilities vs. CSS custom properties, dark mode patterns
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).
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.
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:
