Join the waitlist

Draft a theme from Figma

Give Gamestage your brand's Figma file, get a draft theme on real Gamestage UI components, revise it in plain words, and publish it when it is right.

Give Gamestage your brand's Figma file and get a draft Gamestage UI theme back: each of your colours, corners and type mapped to the role it plays, with the Figma value it came from and why. Say what is wrong in plain words and get a new revision. Nothing is published until you publish it.

$ gamestage theme draft "Kestrel Cup.fig" --name kestrel
Drafted kestrel from Kestrel Cup.fig, as draft td-4k2m9q7x1c3b. It is not published.

10 roles set from Figma
  • color.interactive = #ff5a36  from variable Brand/Flare #ff5a36. The main call to action.
  • button.radius = 8px  from variable Radius/Control 8. Every control's corners.
  ...
See it on real components and revise it in words: https://gamestage.ai/stage/design-systems/drafts?draft=td-4k2m9q7x1c3b

$ gamestage theme revise td-4k2m9q7x1c3b "the answer buttons should be the dark grey from the Game Overlay frame, and less round"
Revision 2 of kestrel.

2 roles changed
  • button.radius = 4px  from Radius/Control 8, halved. Less round, as asked.
  • color.surfaceRaised = #1d1e20  from fill #1d1e20 in Game Overlay. The dark grey asked for.

$ gamestage theme from-draft td-4k2m9q7x1c3b
$ gamestage theme publish kestrel-theme

This chapter is for an organisation admin, at Monterosa or at a customer, who has the customer's Figma file. If your agent already reads Figma and fills tokens.json itself, make your organisation's theme by hand instead: both routes end at the same theme publish.

Before you start

  • Be an organisation admin. Drafts are your organisation's, and only the people who may publish its themes may make them. Run gamestage org admins to see who they are.
  • Have the right frames. Two to five game screens built from layers, such as a question screen and a results screen. A phone mock-up that is one flattened picture holds no colours or sizes, and is refused.
  • Choose how to give the file. A downloaded .fig needs no token. A Figma link needs a personal access token that can read the file.

Draft from a downloaded .fig

In Figma, use File, Save local copy, then:

gamestage theme draft "Kestrel Cup.fig" --name kestrel

The CLI reads the file on your machine and sends Gamestage only the values it found: colours with how often each is used, type, corner radii, spacing, and the variables by mode. It never sends the file, its pictures or its layers. If the Save local copy item is missing, the file's owner has switched downloads off: ask them for the file, or use a link.

Copy a link to the frame (Share, Copy link to selection), set your token in the environment, and draft:

export FIGMA_API_TOKEN=<your token>
gamestage theme draft "https://www.figma.com/design/<key>/<name>?node-id=1-2" --name kestrel

The token goes to Figma and nowhere else. The CLI reads the frame on your machine and sends Gamestage the same values a .fig gives.

In Stage, you can paste a link and a token instead. Gamestage then reads Figma on its side, uses the token for that one read and never stores, logs or forwards it.

Read the draft

Each draft lists:

  • Roles set from Figma: one line per role, with the value, the Figma value it came from and why.
  • Values not used: anything the model suggested that Gamestage UI has no role for, that is in the wrong form, or that failed the theme check, with the reason. These are never published. A value that fails a contrast check is dropped and the library's own value stays.
  • In the designs, with no role to take it: what your screens have that no component covers, such as a badge.
  • Fonts the draft names: families your designs use. A draft never declares a font; see publish it.

--json prints all of it, plus the theme check and what the model call cost.

Revise it in plain words

gamestage theme revise td-4k2m9q7x1c3b "the answer buttons should be the dark grey from the Game Overlay frame, and less round"

Only the roles the words change are changed; every other role keeps its value and its reason. You can name a frame, because the draft keeps what each frame uses. A changed value that fails the theme check keeps the draft's earlier value, and says so.

Go back to an earlier revision

gamestage theme revise td-4k2m9q7x1c3b --to 1

Going back makes a new revision with the earlier roles, so you can come forward again the same way. Every revision is kept, and going back costs nothing against your organisation's limit.

See it on real components

Open the link the draft prints, or Design systems, then Drafts, in Stage. The draft is drawn on real Gamestage UI components: buttons, answers as a list in each state, a results card, text and the colour roles. Load your font files there to see the draft in them; they stay in your browser. Revise it in the What should change? box.

Write it to a folder and publish it

gamestage theme from-draft td-4k2m9q7x1c3b kestrel-theme
gamestage theme check kestrel-theme
gamestage theme publish kestrel-theme

from-draft writes theme.json and tokens.json. It never writes into a folder that already has a theme.json, so your fonts and declarations are never overwritten. Before you publish, add your fonts to theme.json and their files under fonts/: see ship your own font with your theme. theme publish then runs the same checks as always and asks you to declare each font.

Commands

theme draft <figma-url | file.fig | export.json>

FlagWhat it does
--name <name>The theme's name: 3 to 40 lowercase letters, numbers and hyphens. Default: from the Figma file's name.
--org <id>Draft as this organisation for this command only, when you are its admin.
--jsonPrint the draft as JSON.

Exit 0 when the draft passes the theme check, 1 when it does not or was refused, 2 when the file or link could not be read.

theme revise <draft> ["<instruction>"]

FlagWhat it does
--to <revision>Go back to an earlier revision instead of giving an instruction.
--org <id>Work as this organisation for this command only.
--jsonPrint the new revision as JSON.

theme drafts

FlagWhat it does
--org <id>List this organisation's drafts for this command only.
--jsonPrint the list as JSON.

theme from-draft <draft> [dir]

FlagWhat it does
--revision <n>Write this revision rather than the latest.
--version <version>The version written in theme.json. Default 0.1.0.
--org <id>Work as this organisation for this command only.
--jsonPrint what was written as JSON.

What Gamestage sees, and what it keeps

  • From the CLI, Gamestage receives the values the file holds and nothing else: no file, no pictures, no token.
  • From Stage, a .fig is read on Gamestage's side and deleted when the request ends. A link's token is used for that one read and is never stored, logged, put in the draft or sent to the model.
  • The draft is kept privately for your organisation, beside its published themes: the values the model was shown, and every revision. Only your organisation's admins can read it, and Monterosa only processes it.
  • The model runs through OpenRouter, on hosts that keep no data and are not in China. It is shown the values and the role list, never a token.

Limits

LimitValue
Drafts and revisions per organisation20 an hour, 100 a day. Going back is free.
Drafts kept per organisation200
Revisions per draft30
Instruction1,000 characters
.fig sent from Stage3 MB. The CLI reads any size on your machine.
export.json4 MB

When it fails

Each refusal says what went wrong and what to do. The common ones:

CodeWhat happenedWhat to do
flattened_framesThe frames are flattened pictures, so they hold no colours or sizes.Choose frames built from layers, such as a game screen the designer drew.
no_valuesThe file holds no colours, type or variables.Choose the frames with the game's screens, or a file whose variables hold the brand's colours.
not_org_admin, owner_onlyYou are not an admin of the organisation.Ask an admin (gamestage org admins) to draft it, or a Monterosa operator to make you one.
token_missing, figma_token_rejectedNo token, or Figma rejected it.Make a personal access token in Figma that can read files.
access_denied, figma_access_deniedThe token cannot read this file.Ask for access to the file, or use a token from an account that has it.
fig_too_largeA .fig sent from Stage is over 3 MB.Run gamestage theme draft <file.fig>, or use a link.
draft_limitYour organisation reached its hourly or daily limit.Try again at the time the message gives.
model_busy, model_timeoutThe model was busy or slow.Try again; choose fewer frames if it keeps happening.
drafts_unavailable, model_unavailableDrafts are not switched on where you are working.Tell Monterosa.
theme_existsfrom-draft was pointed at a folder that already has a theme.Choose another folder.