Design System Documentation Infrastructure
Bridging Design and Engineering Through AI-Assisted Markdown Documentation
Role: Lead Designer + Documentation Owner
Project: RigCLOUD & SmartROS — Nabors Industries
Status: In progress
Tools: Figma, Figma MCP Server, GitHub Copilot, GitHub, VS Code
“Even with dev seats, they would build whatever they wanted.”
— The problem this project was built to solve
THE SITUATION
Nabors runs two parallel product teams — RigCLOUD and SmartROS — both building complex industrial HMI and enterprise web platforms. Both teams worked with rotating contract developers. A new group every three months. Every time, the same problem: developers had access to Figma but couldn’t translate what they saw into what the design system intended.
Documentation existed — inside Figma. But Figma is a designer’s tool. Developers would open it, misread it, ignore it, or build their own interpretation. The result was production interfaces that looked nothing like the prototypes. Components implemented inconsistently. Tokens ignored. Every new contract cycle started from zero.
Two additional problems compounded this:
No shared standard across designers. Each designer documented differently. There was no unified voice, no consistent structure, no single source of truth a developer could trust.
Annotations in Dev Mode weren’t working. Token names were added as annotations inside Figma’s Dev Mode — the right idea in theory. In practice developers rarely referenced them consistently enough to make a difference.
Something had to change.
MY ROLE
I identified the problem, designed the solution, and own the documentation infrastructure. I am building this across both RigCLOUD and SmartROS simultaneously, in collaboration with both design and engineering teams.
THE INSIGHT
The core problem was not that developers didn’t care about the design system. It was that the design system lived in a place they didn’t work — and in a format they couldn’t use inside their actual workflow.
Developers don’t live in Figma. They live in VS Code. They use GitHub. They increasingly work with AI coding assistants like GitHub Copilot that can read and reference documentation in real time while they build.
The insight: if the design system documentation lived in GitHub as Markdown files, developers could reference it directly inside their coding environment — using natural language prompts — without ever leaving their workflow. The documentation would meet them where they already were.
THE WORKFLOW
Step 1 — Figma variables as the source of truth
Design tokens — color, typography, spacing, elevation, border radius — are maintained as variables inside Figma. This is the canonical source. Everything downstream derives from here.
Step 2 — Figma MCP Server reads the variables
Using the Figma MCP server, the variable data is made accessible programmatically. This is the bridge between the design tool and the documentation layer.
Step 3 — GitHub Copilot generates the Markdown
With VS Code and GitHub Copilot, the variable data is used to generate structured Markdown documentation — component specs, token references, usage guidelines, interaction rules. What would take hours to write manually is generated, reviewed, and refined in a fraction of the time.
Step 4 — Documentation lives in GitHub
The resulting MD files are stored in a GitHub repository accessible to both product teams. Developers reference it directly using Copilot prompts while building — asking questions like “what token should I use for a critical alert background” and getting the correct answer from the documented system.
Step 5 — HTML and CSS scaffolding
The same process generates baseline HTML and CSS files — giving developers something structurally correct to build on from day one. This single addition has had the most immediate visible impact: production interfaces now resemble the prototypes significantly more closely than before.
WHAT CHANGED
Before
- Documentation lived in Figma only — inaccessible in the developer’s workflow
- Every designer documented differently — no shared standard
- Contract developers cycled in every three months and started from zero
- Production builds diverged significantly from design intent
- Dev Mode annotations with token names were inconsistently referenced
After
- Design system documentation lives in GitHub — inside the developer’s environment
- Developers reference it via Copilot prompts while actively building
- HTML and CSS scaffolding gives new contract teams a structurally correct starting point
- Production interfaces now align significantly more closely with design prototypes
- Both RigCLOUD and SmartROS teams share the same documentation infrastructure
WHAT DIDN’T WORK
Dev Mode annotations with token names. The idea was sound — surface the token name directly in the tool developers were already using for inspection. In practice, developers didn’t reference them consistently. The annotation was passive. The GitHub documentation is active — developers pull it into their workflow by choice, using it to answer questions as they build. The difference is agency. Pushed information gets ignored. Referenced information gets used.
WHAT I LEARNED
The design-to-development gap is not a communication problem. It is an infrastructure problem. Designers and developers work in fundamentally different environments with different tools, different mental models, and different workflows. Closing the gap requires meeting developers where they are — not asking them to come to where designers are.
The rotating contract developer reality at Nabors made this unusually visible. Every three months the consequences of bad documentation infrastructure reset and repeated. Building documentation into GitHub — the one tool every developer uses regardless of stack, seniority, or contract length — was the only solution that survived the rotation.
The AI layer — Copilot generating Markdown from Figma variables — was not the point. It was the enabler. The point was making the design system fluent in the language developers actually speak.
STATUS & NEXT STEPS
This project is actively in progress across both platforms. Current focus:
- Completing the token documentation for both RigCLOUD and SmartROS component libraries
- Refining the HTML/CSS scaffolding process based on developer feedback
- Establishing a maintenance workflow so documentation updates automatically when Figma variables change
- Evaluating whether Dev Mode annotations can be retired entirely in favour of the GitHub-first approach
TOOLS & METHODS
Figma — Figma Variables — Figma MCP Server — GitHub Copilot — VS Code — GitHub — Markdown
Active project. RigCLOUD and SmartROS platforms. Nabors Industries, 2025–2026.
Sole Houston | Research-Led UX Design 