theqtcompanyrnd/agent-skills/qt-figma-token-extraction

Figma Token Extraction Skill

This skill extracts design tokens from a Figma file, maps them to QML types, and generates a ready-to-use QML design system with a unified Theme singleton.

Skill Structure

Supporting files are loaded alongside this SKILL.md:

qt-figma-token-extraction/
├── SKILL.md                        # this file — entry point
├── references/
│   └── token-mapping.md            # Figma variable type → QML type mapping rules
└── examples/
    ├── Primitives.qml      # primitive color palette template
    ├── Theme.qml           # semantic token template (references Primitives)
    ├── FontInterface.qml   # font loaders + icon index template
    ├── Spacing.qml         # spacing and radii template
    └── Typography.qml      # typography scale template

When reaching Step 4 (type mapping), read references/token-mapping.md before generating any QML. When generating QML files in Step 6, use the files in examples/ as structural templates — they reflect the real Qt Design Studio naming and organisation patterns.

Step 0 — Check Qt Project Setup

Always call the AskUserQuestion tool — even if a project appears to be open. Never assume the currently open project is the intended target.

Before calling, read the context to personalise the question:

• If a project is already open (files visible, CMakeLists.txt present), name it in the first option so the user can confirm or redirect.
• If the user's request is an update ("update my colors", "re-extract tokens", "sync the design system"), omit the "create new project" option — updates always target an existing project.

For an update request — two options, no "create new":

tool: AskUserQuestion
question: "Which project should I update the design tokens in?"
options:
  - "This project — <detected project name or path> (currently open)"
  - "A different existing project — I'll give you the path"

For an initial setup request — all three options:

tool: AskUserQuestion
question: "Which Qt project should I set up the design system in?"
options:
  - "This project — <detected project name or path> (currently open)"
  - "A different existing project — I'll give you the path"
  - "Create a new project"

If no project is open yet, replace the first option with just "An existing project — I'll give you the path".

If the project exists (confirmed or path provided): Note the project path. Continue to Step 1 — do not ask for Figma files yet.

If a new project is needed: Scaffold the folder structure and create main.cpp and main.qml now, then continue to Step 1:

my-project/
├── CMakeLists.txt      ← set up in Step 7
├── main.cpp            ← create now (template below)
├── main.qml            ← create now (template below)
└── design-system/      ← generated files go here

Create main.cpp with this exact content — use QGuiApplication, not QApplication (Widgets is not needed for Qt Quick):

#include <QGuiApplication>
#include <QQmlApplicationEngine>
 
int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);
    QQmlApplicationEngine engine;
 
    engine.loadFromModule("<ProjectName>", "Main");
 
    if (engine.rootObjects().isEmpty())
        return -1;
 
    return app.exec();
}

Replace <ProjectName> with the URI used in qt_add_qml_module() — they must match exactly.

Do not use the old `QUrl url(u"qrc:/..."_qs)` pattern. In Qt 6, qt_add_qml_module places files under qrc:/qt/qml/<URI>/ — not qrc:/<URI>/ as in Qt 5. Using the old path causes a silent load failure. loadFromModule() avoids this entirely and is the correct approach for Qt 6.5+.

Create Main.qml as a placeholder — capital M, not lowercase. loadFromModule() is case-sensitive and looks for a type named Main, which maps to Main.qml:

import QtQuick
 
Window {
    width:   640
    height:  480
    visible: true
    title:   "My Qt App"
}

CMake setup: The full CMakeLists.txt — including singleton registration — is written in Step 7 once all QML files are known. Do not write it now. If the user encounters any build configuration issues, suggest the user check Qt's CMake documentation at https://doc.qt.io/qt-6/cmake-get-started.html rather than troubleshooting inline.

Step 1 — Routing Questions

Call the AskUserQuestion tool for each question below — one at a time. If the AskUserQuestion tool is not available in the current interface, ask the same question as plain text and wait for the answer before continuing. Do not ask for any Figma links yet.

Call 1 — Modes:

tool: AskUserQuestion
question: "Does your Figma design system use multiple variable modes?"
options:
  - "Yes — for example Light and Dark themes"
  - "No — single mode only"
  - "I'm not sure"

Wait for the answer, then ask:

Call 2 — Terminal:

tool: AskUserQuestion
question: "Are you comfortable running a short command in a terminal on your own computer?"
options:
  - "Yes, I can use a terminal"
  - "No, I prefer not to use a terminal"

If the user answered "I'm not sure" on modes, proceed with MCP and check for modes during extraction. Explain what you find then, not upfront.

Do not ask whether the file uses Variables or Styles. Auto-detect this after receiving the Figma file URL in Step 2 — call get_variable_defs or inspect the file and report what you find. Use Variables extraction if variables exist, Styles extraction if only styles exist, both if both are present.

Step 2 — Collect All Figma File Links

Now that you know the extraction approach, ask for all Figma file URLs in one go — before starting any extraction. This avoids interrupting the workflow later.

Ask the user:

"Please share the URL(s) for all Figma files that contain your design tokens. If your tokens are spread across multiple files or pages (e.g. colours in one file, typography in another), share all of them now and tell me what each file contains."

Wait for all URLs before proceeding. Extract the file key from each URL — the alphanumeric string between /design/ and the next /. Note what token types each file/page contains.

Community files note: If any URL is from a Figma community file the user has not duplicated to their account, warn them now: the extraction tools cannot access community files directly. Ask them to duplicate the file to their drafts in Figma first (open the file → Duplicate to your drafts), then share the new URL.

MCP Method — Extraction via Figma MCP

(Use when: single-mode system, or user is not comfortable with a terminal)

Requires: Figma MCP connected. No personal access token or local setup needed.

Note: This method reads only the currently active variable mode in Figma. If the design system has multiple modes (e.g. Light/Dark) the user will need to switch modes in Figma between reads — workable but more steps. Don't mention this limitation upfront; only explain it if multiple modes are discovered during extraction.

Step 1a — Verify Figma MCP is connected

Before doing anything else, confirm that Figma MCP tools are available. Look for tools whose names suggest variable extraction, design context reading, or file metadata — different Figma MCP servers may use different exact names (e.g. get_variable_defs, getVariableDefinitions, figma_get_variables). Treat the tool names in this skill as examples, not fixed contracts — match by purpose, not exact string.

If no Figma tools are available at all, tell the user:

"The Figma MCP connector isn't connected yet. Connect it in your Claude interface (Settings → Connectors or MCP configuration), then come back and we can start."

Do not proceed until the connection is confirmed.

Step 1b — Check for modes

Call get_variable_defs with the file node ID to see what collections and modes exist:

Tool: get_variable_defs
Input: { "nodeId": "<root node id or specific variable group node id>" }

If the response shows multiple modes and the user wants all of them, explain that you'll need them to switch modes in Figma between reads, and proceed.

Step 1c — Extract variables

Call get_variable_defs on the relevant nodes. Work through token categories one collection at a time — colors, typography, spacing, radii, shadows. For each collection, read the active mode's values.

If multiple modes need to be captured:

• Extract and record all values for the current mode
• Ask the user to switch the active mode in Figma (View menu → Variable Modes, or the mode switcher on the canvas)
• Call get_variable_defs again and record values for the new mode
• Repeat for each mode
• Merge into a single token file with mode keys (see output format in Step 5)

Step 1d — Resolve aliases

If any variable value references another variable (an alias), resolve it to its final value. Do not write unresolved alias references into the output file — flag any that cannot be resolved and ask the user.

curl Method — Extraction from the user's local machine

(Use when: multiple variable modes, and user is comfortable with a terminal)

Requires: Terminal access (curl is built into macOS and Linux; available on Windows 10+), and a Figma Personal Access Token (viewer scope is enough).

Important: Complete all steps in this section — especially PAT setup and verification — before running any curl commands. Running curl with an invalid token will create broken output files.

Community files are not supported. The curl commands only work on Figma files that are in your own account (files you own or have been invited to). Community files you are viewing but have not duplicated will return a 403 error. If the user is working from a community file, ask them to duplicate it to their account first: in Figma, open the community file → click Duplicate to your drafts → use the duplicated file's URL instead.

Step 1a — Set up a Figma Personal Access Token

Do this before anything else. Ask the user:

"Before we run the extraction command, you'll need a Figma Personal Access Token. Do you already have one?"

If yes: proceed to verification (Step 1b).

If no, guide them through creating one:

1. Open Figma in your browser or desktop app

2. Click your avatar (top-left) → Settings

3. Go to the Security tab

4. Scroll to Personal access tokens → click Generate new token

5. Give it any name (e.g. "Claude token export"), set scope to Viewer

6. Copy the token immediately — Figma only shows it once

Step 1b — Verify the PAT works before proceeding

If the PAT was recently verified (within the last 90 days), the user can skip this step. Otherwise, ask the user to run this verification command in their terminal:

curl -H "X-Figma-Token: YOUR_TOKEN" "https://api.figma.com/v1/me"

Expected result: a JSON response containing their Figma account email (e.g. "email": "name@example.com").

If the response contains "status": 403 or "Invalid token": the token is wrong or expired. Ask the user to generate a new one and try again. Do not proceed to extraction until the verification succeeds.

Step 1c — Run the variables extraction

Ask the user to run in their terminal:

curl -H "X-Figma-Token: YOUR_TOKEN" "https://api.figma.com/v1/files/FILE_KEY/variables/local" -o design-tokens-raw.json

This saves the complete raw variable export — all collections, all modes, all values — to design-tokens-raw.json.

Step 1d — Share the result