The intersection of GitLab and Figma represents a sophisticated convergence of design operations (DesignOps) and software engineering, creating a seamless pipeline from conceptual wireframing to production-ready code. In a high-scale environment, the relationship between these two platforms is not merely about sharing links but involves a complex ecosystem of design tokens, automated provisioning, and synchronized state management. By treating design as code, GitLab ensures that the visual language of the product remains consistent across diverse teams and complex architectural landscapes. This integration minimizes the friction traditionally found in the handoff process, replacing static specifications with dynamic, linked references and a shared source of truth.
Figma Provisioning and Access Governance
The management of Figma seats within a professional organization requires a rigorous governance model to balance cost-efficiency with operational necessity. At GitLab, the UX department serves as the primary business owner for Figma, though multiple departments maintain team members with Editor roles to facilitate cross-functional collaboration.
The provisioning process is governed by a Tech Stack YAML file, ensuring that access is tracked as part of the broader organizational infrastructure. Access is not granted arbitrarily; every paid seat must be supported by a Lumos access request and explicit budget approval. This prevents "seat creep" and ensures that the organization only pays for the capacity it actually utilizes.
Figma offers four distinct seat types, each tailored to specific organizational roles:
- View: This is the default seat type. Access is requested via Lumos and is auto-approved, as it carries no financial cost.
- Full: This seat provides comprehensive access to the entire Figma suite, including Figma Design, Figma Make, Dev Mode, Figma Draw, Figma Slides, and FigJam.
- Dev: Specifically designed for engineers, this seat provides access to Dev Mode, Figma Slides, and FigJam, while restricting Figma Design files to view and comment access.
- Collab: Tailored for collaborators who need FigJam and Figma Slides, while maintaining view and comment access in Figma Design files.
The operational workflow for granting access involves a specific chain of command. Once a Lumos request is initiated, provisioners are automatically notified. The provisioner must validate three critical criteria before granting the seat: the manager's approval, the user's understanding of which seat they actually require, and the confirmation of budget availability. A critical distinction is maintained between Full and Collab seats to prevent over-provisioning of expensive licenses. Notably, seat upgrades are strictly handled via Okta access through Lumos; using Figma's internal admin or sharing tools to upgrade seats is prohibited to maintain auditability and budget control.
Design Token Synchronization and the Single Source of Truth
Design tokens are the atomic elements of a design system, representing values such as colors, spacing, and typography. GitLab utilizes a sophisticated synchronization mechanism via the Tokens Studio plugin to bridge the gap between Figma and GitLab repositories.
The integration utilizes the GitLab Sync Provider, which allows for a two-way synchronization of design tokens. This means that JSON files containing design tokens can be pushed from Figma into a GitLab repository and, conversely, pulled from GitLab back into any Figma file. By storing these tokens in a code repository, the tokens living in code become the absolute source of truth. This eliminates the "drift" that occurs when designers update a color in Figma but engineers are still using an outdated hex code in the CSS.
The setup process for this synchronization involves the following technical steps:
- Creation of a GitLab account and a dedicated repository for tokens.
- Generation of a personal access token within GitLab to allow the plugin to authenticate.
- Configuration of GitLab as the sync provider within the Tokens Studio plugin.
- Execution of Push and Pull commands to maintain parity between the design environment and the codebase.
UI Kit Components and Structural Hierarchy
The organization of components within Figma is critical for discoverability and scalability. GitLab employs a strict hierarchy to ensure that the asset library remains intuitive for both designers and developers. The default structural hierarchy follows the path: File / Page / Frame / Layer.
To organize components, GitLab uses two primary methods: Figma's native Variants feature and a slash-based naming convention. The working hierarchy for naming and structure is defined as follows:
- Page: Defined by the [Component] name.
- Frame: Structured as [Component], [Category], [Group], [Elements] or simply labeled "Variants."
- Layer: Defined by [Property=Value, Property=Value] when using variants, or [Breakpoint/Item/Size/State] for manual organization.
To handle responsiveness and scaling, the system incorporates optional breakpoints and sizes:
- Breakpoints: xs, sm, md, lg, xl. These may also use symbols to indicate ranges, such as
≥md(greater than or equal to medium) or≤sm(less than or equal to small). - Sizes: xs, sm, md, lg, xl, xxl.
When a component is created as a variant, Figma ensures that only a single instance of that component appears in the asset library, reducing clutter and improving the efficiency of the design process.
Action Design Tokens and Utility Classes
The GitLab UI employs specific design tokens to maintain a consistent visual style for interactive elements. These tokens are categorized by the "action" they represent, ensuring that users can intuitively understand the result of an interaction based on its visual cues.
Action design tokens support three primary contexts:
- neutral: Used for the majority of standard actions.
- confirm: Used for actions that result in a positive outcome.
- danger: Used for actions that are potentially destructive.
To implement these, designers combine background, foreground, and border color tokens. In certain environments, such as Windows High Contrast Mode, borders may be intentionally invisible to provide accessible boundaries. Interactivity is further communicated through defined states, including hover, focus, and active.
For engineering implementation, GitLab provides utility classes that apply the full set of action tokens via a single Tailwind class. This reduces the amount of custom CSS required and ensures adherence to the design system.
| Class | Description |
|---|---|
gl-action-neutral-colors |
Applies neutral action foreground, background, and border colors for all states (default, hover, focus, active). |
gl-action-confirm-colors |
Applies confirm action foreground, background, and border colors for all states (default, hover, focus, active). |
gl-action-danger-colors |
Applies danger action foreground, background, and border colors for all states (default, hover, focus, active). |
An example of the implementation in HTML is as follows:
```html
```
Code Connect and the Dev Mode Bridge
Code Connect serves as the technical bridge between the codebase and Figma's Dev Mode. It allows components in a repository to be linked directly to components in design files. This integration is particularly powerful because it enhances the Figma MCP (Model Context Protocol) server's ability to provide AI agents with precise implementation details, as the AI can reference actual code rather than guessing based on visual representation.
There are two primary implementation paths for Code Connect:
- Code Connect UI: This method operates entirely within the Figma interface. It is language-agnostic and ideal for teams seeking a visual way to link components. It can connect directly to a GitHub repository or use manual paths and names for other version control systems. It provides component paths and names and generates enhanced AI code examples.
- Code Connect CLI: This tool runs locally within the developer's repository, offering greater precision and flexibility for those who need to automate the connection process or handle complex mapping.
Figma Process Guidelines for Marketing and Engineering
To ensure a smooth transition from design to development, GitLab's marketing team follows a strict set of process guidelines. These rules are designed to minimize feedback loops and provide engineers with clear, actionable files.
The naming convention for master projects follows a Parent page / Child page structure. For example:
- Solutions / DevSecOps
- Pricing Page
Master project files are further detailed by version and phase:
- Solutions / DevSecOps / Wireframes / 1.0
- Solutions / DevSecOps / Design / 1.0
- Pricing Page / Mock / 1.0
Within the Figma files, page names must be short and clear. To signal that a page is ready for engineering, designers must use the ship icon in the page title:
🚢 PAGE NAME 🚢
To maintain alignment with engineering updates, MVCs (Minimum Viable Components) are labeled with version numbers such as 1.0, 1.1, 1.2, and 2.0.
Furthermore, designers are encouraged to use READ:ME frames. These frames are essential when:
- Additional rationale is needed to provide clarity.
- Functionality is outlined that cannot be visually depicted.
- Key decisions from long Issue or Merge Request (MR) threads are listed.
- Links to important documentation or issues are required.
Communication is centered around GitLab Issues and MRs. When a specific design element needs to be highlighted, designers are instructed to use the "link to selected frame" feature in Figma to provide an exact reference point within the design file.
Production Architecture and Infrastructure Constraints
While the design process happens in Figma, the eventual deployment occurs within a complex production architecture. Understanding this infrastructure is vital for designers and engineers who must consider how the UI interacts with the underlying services.
GitLab's production environment utilizes a highly segmented network strategy. Monitoring infrastructure, including InfluxDB and Prometheus, flows through a peered ops network. For alert management, all networks are peered together to ensure that a cluster of alert managers can trigger notifications regardless of individual environment failures.
The external-facing layer is managed via Cloudflare's Web Application Firewall (WAF). DNS hosting is split between Cloudflare and Amazon Route 53:
- gitlab.com and gitlab.net are hosted with Cloudflare.
- gitlab.io and other domains are hosted with Amazon Route 53.
A strict naming convention is applied to services:
- All services providing "GitLab as a service" are placed in the gitlab.com domain.
- Ancillary services (such as Chef, ChatOps, VPN, Logging, and Monitoring) are placed in the gitlab.net domain.
Access to this production environment is strictly controlled and granted only to essential personnel via bastion hosts, ensuring that the design-to-code pipeline terminates in a secure, audited environment.
Conclusion: The Synthesis of Design and Engineering
The integration of Figma into the GitLab ecosystem is not a simple matter of tool adoption but a comprehensive architectural strategy. By implementing a rigorous provisioning system, the organization ensures that the right people have the right access without inflating costs. The use of design tokens and the Tokens Studio plugin transforms the design process from a subjective exercise into a data-driven operation, where a JSON file in a GitLab repository dictates the visual state of the product.
The implementation of Code Connect further evolves this relationship, moving beyond static handoffs to a state of "live" connection where the design file is aware of the code it represents. This is augmented by a strict naming and structural hierarchy in the UI Kit, ensuring that as the product grows, the design system does not collapse under its own complexity. When combined with the disciplined process guidelines—such as the use of 🚢 icons and READ:ME frames—the result is a highly efficient machine that converts a design hypothesis into a production reality with minimal friction. The overarching goal is the elimination of ambiguity, ensuring that what is designed in Figma is exactly what is deployed across the gitlab.com and gitlab.net infrastructures.