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.

1. Read peerDependencies: Run npm info @gitlab/ui peerDependencies --json (or inspect the package.json in the installed package) to discover required Vue version, etc.
2. 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.
3. 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:

1. Search the token map: Read references/design-tokens/token-map.md and search for the exact value
2. If exact match found: Use that token
3. 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
4. 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)

1. Pajamas components — use GlButton, GlAlert, etc. which apply tokens automatically
2. CSS utility classes — gl-bg-subtle, gl-text-default, gl-p-3, gl-rounded-base
3. CSS custom properties — var(--gl-background-color-default) when utilities don't cover the case
4. 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

1. Consult the index: Read references/component-index.md to find the relevant component, pattern, or foundation by name
2. 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
3. Check related components: Each doc's YAML frontmatter includes a related: list — review related components when choosing between alternatives
4. 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:

1. 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.
2. 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.
3. 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.
4. 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.
5. 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:

1. implement-design fetches design context and screenshots from Figma
2. This skill maps the Figma output to the correct Pajamas components and design tokens
3. 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):

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:

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:

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