TLDR: This process connects Figma Dev Mode and GitLab to automatically turn design prototypes into validated user stories, tickets, and audits with full traceability. It eliminates manual handoffs, enforces quality gates, and gives teams and leadership a clear, end-to-end view from design to production.
1. Overview
This document defines the unified process for converting design prototypes into structured user stories using Figma Dev Mode integrated with GitLab. The process allows designers to work fully within Figma while ensuring automatic synchronization of design artifacts, feature files, and ticket stubs to GitLab.
Objectives
- Centralize design and user story generation in Figma.
- Automate transfer of design outputs to GitLab.
- Enforce traceability between prototypes, user stories, and tickets.
2. End-to-End Workflow
2.1 Flow Summary
- Designers create clickable prototypes in Figma.
- AI prompts (from a shared Prompt Library) are run inside Figma’s Dev Mode.
- AI-generated outputs (Markdown, Gherkin, and audit reports) are saved in Figma’s AI Output panel.
- Designers export deliverables to GitLab through the Export to GitLab Dev Mode action.
- A GitLab CI/CD pipeline validates, lints, and converts files into Issues and Merge Requests.
- PMs and Engineers review, refine, and approve the Merge Request.
2.2 Key Deliverables
- PrototypeAudit.md – AI-generated prototype analysis.
- .feature files – Gherkin format user stories.
- TicketStubs.md – Suggested ticket breakdown.
- Audit Reports – Linked to Figma frame IDs.
3. GitLab Repository Structure
Recommended top-level layout:
product/<project_name>/ figma/ → Design artifacts exported from Figma prompts/ → Shared prompt packs for AI agents stories/ → Gherkin .feature files tickets/ → AI-generated ticket stubs
Example:
product/ <project_name>/ figma/prototype_link.txt figma/frame_map.csv figma/audit.md prompts/00-context.md prompts/10-prototype-review.md prompts/20-story-generator.md prompts/30-acceptance-checklist.md stories/auth_login.feature tickets/TicketStubs.md
4. Figma Dev Mode Process
4.1 Inside Figma
- Designers build the prototype with clear, verb–noun frame names.
- AI prompts are executed through a shared Prompt Library Component.
- Generated outputs appear in the AI Output section.
- Designers select Export to GitLab in Dev Mode.
- Figma creates a feature branch in GitLab named
feat/<project_name>/figma-ai-drop. - A Merge Request is automatically created with linked artifacts.
4.2 GitLab Automation
A GitLab CI pipeline runs automatically:
- Lint and validate all
.featurefiles. - Check frame coverage using
frame_map.csv. - Generate GitLab Issues from Scenarios.
- Notify messaging channels on completion.
5. Prompt Library Structure
5.1 Required Prompts
- 00-context.md – Establishes design and artifact metadata.
- 10-prototype-review.md – AI audits flows, CTAs, and interactions.
- 20-story-generator.md – Generates Gherkin stories.
- 30-acceptance-checklist.md – Appends acceptance tests.
- 40-ticket-export.md – Converts Scenarios to ticket stubs.
5.1.1 prompts/00-context.md
# Context Use this file as the top-level context for the AI agent inside Figma Dev Mode. Replace placeholders within {{}} with real values before running. [FIGMA_CONTEXT] file_url: {{file_url}} project: {{project_name}} persona: {{persona}} goal: {{goal}} flow: {{flow_name}} frame_map_csv_attached: true output_paths: audit: product/{{project_name}}/figma/audit.md stories: product/{{project_name}}/stories/ tickets: product/{{project_name}}/tickets/TicketStubs.md [/FIGMA_CONTEXT]
6. GitLab CI Configuration
6.1 Minimal .gitlab-ci.yml
stages: - validate - scaffold - publish
7. Supporting Scripts
7.1 check_coverage.py
import sys, pandas as pd, os, re
7.2 create_gitlab_issues.sh
#!/bin/bash FEATURE_DIR=$1 PROJECT_ID=$2 MR_ID=$3 TOKEN=$4
8. Gherkin File Front Matter
Each .feature file includes metadata linking to Figma frames.
9. Quality Gates
- Prototype Coverage – Frame-to-scenario validation passes.
- Clarity – Gherkin linting passes with no style-based assertions.
- Testability – Each form has input permutations via Scenario Outlines.
- Traceability – All feature files contain valid front matter.
- Handoff Hygiene – MR includes audit.md and follows template standards.
10. Designer Quick Start
- Run Audit Prototype AI prompt.
- Run Generate Stories AI prompt and review the output.
- Use Export to GitLab in Dev Mode.
- Open the Merge Request link to monitor CI validation.
- Resolve any CI feedback.
11. Security and Permissions
- Use GitLab OAuth or a Project Access Token with minimal scope.
- Store tokens as protected CI variables or in a secure server endpoint.
- Restrict branch names and file paths through CI validation.
12. Optional Future Enhancements
- Auto-generate Playwright test skeletons from Gherkin.
- Publish AI audit documentation through GitLab Pages.
- Post coverage summaries to messaging channels automatically.
13. Summary
This integrated process eliminates tool switching and ensures a continuous, auditable flow from prototype to production-ready stories. Designers remain in Figma, developers manage validation in GitLab, and leadership gains visibility into progress, quality, and traceability through automated pipelines.
