3 min read -
I ran my own Figma file through last week, the way an agent reads it, and got two of these wrong. So this is the list I made for myself rather than one I am handing down. Walk it yourself, or point an agent at the file if you have Figma connected over MCP.
None of it is new. It is ordinary file hygiene, the sort anyone picking up your file will be glad of, human or machine. It just used to be optional. If you would rather see it done live, I am walking through all of it in three free sessions this September (link below).
The five
1. Text styles, named semantically. Mine go font, then headline, then lg. Family, then role, then step within that role. The style is also the bundle that travels, where a loose text layer carries nothing at all. Check with your developers first, because if they already have a naming convention, use theirs.
2. Values as variables. Font family, size and weight bound rather than typed in. A number arrives as a number. A bound variable arrives with a name, which means the decision travels and not only the value.
3. Descriptions. Do and do not, in plain words. What it is for, and what it is not for. Mine were empty on every single text style, which I only noticed when something read the file back to me. That was the big one for me.
4. Modes for breakpoints, with the range inside the mode name. Mine read lg (>1280), md (>800), sm (<800). Call them Mode 1, 2 and 3 and the values arrive with no idea of when they apply. Agree on a set of breakpoints before you start, not after.
5. Scope. What is this variable actually for. Leave it unscoped and it turns up everywhere, which is how a raw brand colour ends up as body text. In colour I unscope the primitive collection entirely and hide it from publishing, then scope only the semantics.
Why my typography has no semantic layer
This is the part I am still turning over, so tell me if you see it differently.
My type variables are primitives only, with nothing semantic above them, while my colours have both layers. That is deliberate. With type, the style already is the semantic layer. font/headline/md carries the meaning, so a semantic variable underneath would only be a hop with a name on it.
Colour has nothing playing that part. A component binds the fill directly, so the semantic layer is the only place the meaning can sit, which is why primitives and semantics both matter there and not here.
I am still exploring this setup, so if you have landed somewhere else I would like to hear it. Just hit reply, I read everything.
See the three free September sessions
The longer, messier version of working with AI as a designer.
I went on Wireframe with Donnie D'Amato and said out loud what I usually keep to a sentence. Design-to-code with AI is a mess; most of what you see online is just tape over the gaps, and the teams in the middle are the ones left holding the bag. We also got into why I refuse to give up the canvas, and why almost nobody in this field wants to admit what they do not know. Watch the episode on YouTube:
|
Moonlearning upcoming
Design Figma Files That Scale with AI FREE
Online, 10 September 2026, 30 min 路 Sign up now
From Team to System: Figma and AI Workflows FREE
Online, 17 September 2026, 30 min 路 Sign up now
Design with Figma, Claude and MCP: An Honest Introduction FREE
Online, 29 September 2026, 30 min 路 Sign up now
Build Scalable UI in Figma, Designers Ready for Agentic AI
Online, 4-week hybrid course, next cohort October 2026 路 Sign up now
See all video courses -->
See all live workshops -->
Team training -->
Want to learn more about Figma to code and AI?
These tools were built for a human developer reading your file, not for a pipeline. That gap is where most of the frustration sits, and almost nobody names it. So I do, in the slow and unglamorous version.
A moonlearning.io membership covers all of it, from Figma basics through UI and UX principles to building and shipping your own products. Become the designer engineers trust, with or without AI.
Video courses 路 Live workshops 路 Team training
The Solo, my book 路 LinkedIn 路 Past issues
You are getting this because you signed up at moonlearning.io.
Responses