The intersection of collaborative design and version-controlled development is most prominently realized through the integration of Figma and GitLab. This synergy allows organizations to bridge the gap between visual conceptualization and technical implementation, transforming static designs into living, breathable design systems. By utilizing GitLab as a source of truth for design tokens and employing a structured Figma process, teams can eliminate the friction typically found in the design-to-development handoff. This integration is not merely about file sharing; it is about creating a bidirectional pipeline where design decisions are codified, tracked, and synchronized across the entire software development lifecycle.
Figma Process Guidelines for GitLab Marketing
For the GitLab marketing team, Figma is not just a canvas but a structured environment that requires strict organizational discipline to ensure scalability and clarity for engineers. The process is designed to accommodate three primary personas: the designers creating the visuals, the reviewers providing feedback, and the engineers implementing the final product.
The naming convention for master projects follows a hierarchical structure to maintain a clear taxonomy. Projects are organized by Parent page and Child page. For example, a project residing under the Solutions parent page may have a DevSecOps child page, or there may be a standalone Pricing Page.
Master project files are further granularized using a four-tier naming convention: Parent page / Child page / Type or Phase / Version. This allows for precise version control and historical tracking. Examples of this structure include:
- Solutions / DevSecOps / Wireframes / 1.0
- Solutions / DevSecOps / Design / 1.0
- Pricing Page / Mock / 1.0
Within the Figma files themselves, page management is critical for engineering handoffs. Page names must be kept short and clear to avoid ambiguity. To signal that a design has reached a state of maturity suitable for development, the ship icon is utilized. Pages ready for engineering are labeled as 🚢 PAGE NAME 🚢.
The organizational layout typically places these ship-labeled pages at the top of the file, separated from the "working" or "draft" pages by a divider. This visual hierarchy prevents engineers from accidentally implementing an outdated iteration of a design. Furthermore, the use of MVCs (Minimum Viable Changes), such as versions 1.0, 1.1, 1.2, or 2.0, ensures that the design versions align perfectly with the engineering update cycles.
To mitigate communication gaps and reduce the volume of unnecessary feedback loops, the use of READ:ME frames is encouraged. These frames serve as an internal documentation layer within the design file and are essential when:
- Additional rationale is required to provide clarity on a specific design choice.
- Functionality needs to be outlined that cannot be visually represented through a prototype or mockup.
- Key decisions derived from long GitLab issue threads or Merge Request (MR) discussions need to be summarized.
- Links to critical external documentation or specific GitLab issues are required.
While Figma commenting is available for discretionary use, the primary mode of feedback should remain within GitLab Issues and MRs. When a specific design element needs to be referenced, designers are encouraged to use the "link to selected frame" feature to provide a direct deep-link from the GitLab issue to the exact coordinate in the Figma file.
Synchronizing Design Tokens via Tokens Studio and GitLab
Design tokens act as the atomic unit of a design system, representing values such as colors, spacing, and typography. By using the Tokens Studio plugin, these tokens can be synchronized directly with a GitLab repository, ensuring that the code and the design are always in alignment.
The Role of Personal Access Tokens
The connection between Figma and GitLab is authenticated using a Personal Access Token (PAT). This is a secure passcode generated within GitLab that grants the Tokens Studio plugin the necessary permissions to read and write to a repository.
The process for generating a PAT involves the following steps:
- Navigate to the GitLab account settings.
- Select the user avatar in the top left corner.
- Select Edit Profile.
- Navigate to the Access Tokens section in the left sidebar.
- Click Add new token.
- Assign a specific name to the token, such as
test-token repo sync to tokens studio. - Select an expiration time frame.
- Provide a description to ensure the token's purpose is remembered.
- Select the required scopes; specifically, the API option must be selected to grant the plugin both read and write permissions.
- Select Generate token.
Once generated, the token must be saved securely, as it is required for the subsequent plugin configuration in Figma.
Configuring the Sync Provider
After obtaining the PAT, the Tokens Studio plugin in Figma must be configured to recognize GitLab as the storage provider. This is achieved by navigating to the Settings page within the plugin and selecting Add new under the Sync providers section. From the list of available providers, GitLab is selected.
The synchronization provides two-way functionality:
- Push: The ability to send JSON files containing design tokens from Figma to a GitLab repository.
- Pull: The ability to retrieve token data stored in GitLab and apply it to any Figma file.
This bidirectional flow establishes the GitLab repository as the single source of truth, ensuring that design decisions are shared transparently between the design and development teams.
Token Storage Strategies: Folder vs. File
Tokens Studio offers two distinct methods for storing data in GitLab, which impact how engineers interact with the tokens and how the data is organized.
| Storage Method | Description | Engineering Impact | License Requirement |
|---|---|---|---|
| Folder | Syncs data into a folder containing multiple JSON files or subfolders. | Optimized for token transformation stages in development. | Tokens Studio Pro |
| File | Syncs all token data into a single JSON file (e.g., tokens.json). |
Simpler structure, but less granular. | Free Version Compatible |
When using the Folder option, the user enters the pathway of the folder without any extensions (e.g., tokens). In this configuration, every Token Set created in the plugin is saved as an individual JSON file within that folder. Additional data files, such as themes and configuration, are also stored here. This is a professional-grade feature; if team members do not possess a Pro License, the tokens will be read-only for them.
Conversely, the File Path option is used when all token data is combined into one single JSON file, such as tokens.json. This is the recommended path for users on the free version of Tokens Studio or for projects where engineers do not need to consume the tokens directly in code.
For organizations running an enterprise server, a Base URL must be provided in the GitLab credentials. This can be identified by checking the repository URL; if a name appears between gitlab and .com, an enterprise server is in use.
Figma Provisioning and User Management
The management of Figma seats within an organization is tied to procurement and employment status to ensure cost-efficiency and security.
Paid seats are tracked as line items on invoices. These invoices must be uploaded to Coupa and processed through the formal procurement workflow. The lifecycle of a seat is managed as follows:
- Deprovisioning: Users are automatically fully deprovisioned from Figma once they are no longer employed by GitLab.
- Downgrading: A paid seat can be downgraded to an unpaid View seat upon request to the IT department.
- Inactivity: Any paid seat that has remained inactive for 90 days will be automatically downgraded to a View seat by the system.
When a member is removed from the organization, their files remain within the organizational boundary. Figma administrators maintain the ability to view and manage these files. Furthermore, any other user who had "can edit" access to the removed member's files retains that access and can move the files as needed.
Community Evolution and the GIMP UX Project
The application of these professional design workflows is evident in community-driven projects, such as the effort to bring GIMP's user interface up to a modern, Figma-level standard. The GIMP UI has historically been criticized as appearing "hacked together by non-designers," leading to a push for professional UX/UI contributions.
While some suggested creating a public Figma file for community editing and discussion—similar to the approach used by OSU!—the actual design discourse has migrated to a specialized UX repository. The primary hub for these discussions is found in the GIMP UX GitLab repository: Issues · Teams / GIMP / Design / GIMP UX · GitLab.
This shift toward GitLab for UX discussion allows for a more systematic approach to design. Community members and professional designers contribute by posting issues and joining discussions, which directly shapes the development of new tools, such as the implementation of upcoming vector layers in GIMP 3. This demonstrates the practical application of using GitLab not just for code, but as a collaborative platform for high-level design strategy and user experience refinement.
Conclusion
The integration of Figma and GitLab represents a transition from fragmented workflows to a unified Design Operations (DesignOps) ecosystem. By implementing a rigorous naming convention and the use of "ship" icons, GitLab ensures that the transition from design to engineering is seamless and devoid of ambiguity. The use of the Tokens Studio plugin further codifies this relationship, transforming aesthetic choices into version-controlled JSON data, which serves as a definitive source of truth.
The technical sophistication of this setup is highlighted by the ability to choose between folder-based and file-based synchronization, allowing teams to scale their design systems based on their license level and engineering requirements. When combined with strict seat management and the use of GitLab for UX discourse—as seen in the GIMP project—the result is a professionalized environment where design is no longer a prerequisite to development, but a continuous, synchronized part of the build process. The synergy of these tools reduces the risk of "design drift" and ensures that the final product is a pixel-perfect realization of the original vision.