• 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.

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"

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"

"An existing project — I'll give you the path"

main.cpp

main.qml

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

main.cpp

QGuiApplication

QApplication

#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();
}

<ProjectName>

qt_add_qml_module()

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+.

Main.qml

loadFromModule()

Main

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.

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"

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"

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.

"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."

/design/

/

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.

get_variable_defs

getVariableDefinitions

figma_get_variables

"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."

get_variable_defs

• 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)

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.

"Before we run the extraction command, you'll need a Figma Personal Access Token. Do you already have 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

• Upload

  design-tokens-raw.json

  to the conversation, or
• Paste its contents into the conversation

Note: Figma Styles (text, color, effect) live separately from Variables and need their own extraction step. If the user's design system uses Styles as the primary token source (not Variables), this step becomes the main extraction — not a secondary one. If the design system uses both Variables and Styles, complete Step 1 first then do this step.

Page-by-page approach: Figma files often spread token types across multiple pages (e.g. Colors on one page, Typography on another). Do not try to extract everything at once. Ask the user which page contains which token type, then extract one page at a time. Confirm what was found after each page before moving to the next.

• All files extracted: Confirm every file the user mentioned has been extracted. Do not proceed if any are missing.
• Collections present: Do the collection names match what the user expects from each file?
• Modes captured: If multi-mode, confirm all modes appear with correct values.
• Color values: Spot-check a few hex values against the Figma file.
• Alias resolution: Semantic tokens that reference primitives should have resolved values. If an alias could not be resolved, it almost certainly means the referenced primitive lives in a file that hasn't been extracted yet — go back and extract that file before continuing.
• Missing collections: If something expected is absent, ask the user which Figma file it lives in and add it to the inventory.

references/token-mapping.md

color

int

real

string

{family}_{scale}

neutral_900

neon_500

QtObject

Primitives.neutrals.neutral_900

{role}_{variant}

background_default

text_muted

Theme.background_default

_default

_muted

_subtle

stroke_strong

stroke_muted

stroke_subtle

notification_{type}_{variant}

notification_alert_default

notification_danger_muted

x{multiplier}

x4

x8

radius_{size}

radius_s

radius_m

radius_full

interFont

titilliumSemiBold

inconsolata

{icon_name}_{size}

close_16

settings_fill_16

snake_case

figmaName

design-tokens.json

JSON vs QML naming: These conventions apply to the generated QML output.

design-tokens.json

stores token keys in camelCase (e.g.

backgroundPrimary

,

cornerRadiusM

) for JSON compatibility — the conversion to snake_case happens when generating QML in Step 6.

design-system/
├── Primitives.qml      ← raw color palette (nested by family: neutrals, accents)
├── Theme.qml           ← semantic color tokens (references Primitives)
├── Spacing.qml         ← spacing steps and corner radii
└── FontInterface.qml   ← font loaders + icon unicode index

No hand-written qmldir. Module registration is handled by

qt_add_qml_module()

in CMakeLists.txt. Singleton registration uses

set_source_files_properties

— updated in Step 7.

• Every value comes from

  design-tokens.json

  — never hardcode values not in the token file
• Use

  snake_case

  throughout —

  background_default

  ,

  neutral_900

  ,

  x4

  ,

  radius_m

• Primitives.qml

  holds raw values only — no semantic meaning.

  Theme.qml

  holds semantic tokens only — always referencing

  Primitives

  , never raw hex values
• Apply type mapping from

  references/token-mapping.md

  —

  readonly property color

  for colors,

  readonly property int

  for sizes,

  readonly property string

  for font names
• Include the source comment and CMake note at the top of every file
• Group related properties with section comments (

  // ── Section name ─────

  )
• If a token is missing from the JSON, leave a

  // TODO: <figmaName>

  placeholder rather than guessing a value
• Imports: Use

  import QtQuick

  —

  import QtQuick.Window

  is redundant in Qt 6 (Window is already included) but not an error if added
• Effects and gradients: Use

  MultiEffect

  from

  import QtQuick.Effects

  (available from Qt 6.5). Never use

  Qt5Compat.GraphicalEffects

  — it requires an extra compatibility module and is not available in all Qt 6 configurations
• QML coding skill: If the

  qt-development-skills:qt-qml

  skill is available, use it when generating QML files to ensure correct Qt 6 patterns are applied

• Check for any

  // TODO:

  placeholders — flag these to the user and ask how to resolve them
• Verify every property type matches the

  references/token-mapping.md

  rules
• Confirm

  pragma Singleton

  and

  import QtQuick

  are present in every file
• Check that no values are hardcoded that should come from the token file

CMakeLists.txt

qt_add_qml_module()

QML_FILES

set_source_files_properties

Naming rule: The target name, URI, and

loadFromModule()

call in

main.cpp

must all use the same project name string. Use the actual project name from the

project()

CMake call — do not substitute

MyProject

literally.

cmake_minimum_required(VERSION 3.16)
project(<ProjectName> VERSION 0.1 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

Replace every `<ProjectName>` with the same string — e.g. `MyQtApp` — matching the `project()` call and the `loadFromModule("<ProjectName>", "Main")` call in `main.cpp`.

After updating CMakeLists.txt, confirm with the user that the file has been saved and show them how to use the singletons in `Main.qml`:

```qml
import QtQuick         // Window is part of QtQuick in Qt 6 — do NOT add import QtQuick.Window
import <ProjectName>   // imports all singletons from the module

Window {
    visible: true
    width: 640
    height: 480
    color: Theme.background_default
}

CMake issues: If the user has build errors after updating CMakeLists.txt, suggest the user check Qt's CMake documentation at https://doc.qt.io/qt-6/cmake-get-started.html rather than troubleshooting inline.

• Total tokens extracted per category (colors, spacing, typography, radii)
• Modes and themes captured
• Any unresolved aliases or

  // TODO:

  placeholders that need attention
• Files produced:

  design-tokens.json

  ,

  Primitives.qml

  ,

  Theme.qml

  ,

  Spacing.qml

  ,

  FontInterface.qml

• Reminder that

  set_source_files_properties(... QT_QML_SINGLETON_TYPE TRUE)

  must be set in CMakeLists.txt for each singleton file
• Use the Token Categories Checklist at the end of this file to verify nothing was missed
• Confirmation that the design system foundation is ready — the component generation skill can now begin

• Primitive color palette (all color families and scales)
• Semantic color tokens with all modes (if present)
• Font families (heading, body, mono)
• Font weights (numeric: 400/500/600/700)
• Type scale from variables (size + weight + line height per role, if defined as variables)
• Text styles (H1–H6, body, label, caption, code — font family, size, weight, line height, letter spacing)
• Spacing scale (base unit + all named steps)
• Corner radii (S, M, L, Full)
• Shadows / elevation levels (if present)
• Icon size tokens (if present)
• Animation / duration tokens (if present)