# Draft a theme from Figma

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](/docs/organisation#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.

## Draft from a Figma 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](https://gamestage.ai/stage/design-systems/drafts), 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](#write-it-to-a-folder-and-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](https://gamestage.ai/stage/design-systems/drafts). 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](/docs/organisation#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>`

| Flag | What 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. |
| `--json` | Print 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>"]`

| Flag | What 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. |
| `--json` | Print the new revision as JSON. |

### `theme drafts`

| Flag | What it does |
| --- | --- |
| `--org <id>` | List this organisation's drafts for this command only. |
| `--json` | Print the list as JSON. |

### `theme from-draft <draft> [dir]`

| Flag | What 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. |
| `--json` | Print 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

| Limit | Value |
| --- | --- |
| Drafts and revisions per organisation | 20 an hour, 100 a day. Going back is free. |
| Drafts kept per organisation | 200 |
| Revisions per draft | 30 |
| Instruction | 1,000 characters |
| `.fig` sent from Stage | 3 MB. The CLI reads any size on your machine. |
| export.json | 4 MB |

## When it fails

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

| Code | What happened | What to do |
| --- | --- | --- |
| `flattened_frames` | The 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_values` | The 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_only` | You 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_rejected` | No token, or Figma rejected it. | Make a personal access token in Figma that can read files. |
| `access_denied`, `figma_access_denied` | The token cannot read this file. | Ask for access to the file, or use a token from an account that has it. |
| `fig_too_large` | A `.fig` sent from Stage is over 3 MB. | Run `gamestage theme draft <file.fig>`, or use a link. |
| `draft_limit` | Your organisation reached its hourly or daily limit. | Try again at the time the message gives. |
| `model_busy`, `model_timeout` | The model was busy or slow. | Try again; choose fewer frames if it keeps happening. |
| `drafts_unavailable`, `model_unavailable` | Drafts are not switched on where you are working. | Tell Monterosa. |
| `theme_exists` | `from-draft` was pointed at a folder that already has a theme. | Choose another folder. |
