{"doc":"theme-from-figma","title":"Draft a theme from Figma","markdown":"# Draft a theme from Figma\n\nGive Gamestage your brand's Figma file and get a draft Gamestage UI theme back:\neach of your colours, corners and type mapped to the role it plays, with the\nFigma value it came from and why. Say what is wrong in plain words and get a\nnew revision. Nothing is published until you publish it.\n\n```\n$ gamestage theme draft \"Kestrel Cup.fig\" --name kestrel\nDrafted kestrel from Kestrel Cup.fig, as draft td-4k2m9q7x1c3b. It is not published.\n\n10 roles set from Figma\n  • color.interactive = #ff5a36  from variable Brand/Flare #ff5a36. The main call to action.\n  • button.radius = 8px  from variable Radius/Control 8. Every control's corners.\n  ...\nSee it on real components and revise it in words: https://gamestage.ai/stage/design-systems/drafts?draft=td-4k2m9q7x1c3b\n\n$ gamestage theme revise td-4k2m9q7x1c3b \"the answer buttons should be the dark grey from the Game Overlay frame, and less round\"\nRevision 2 of kestrel.\n\n2 roles changed\n  • button.radius = 4px  from Radius/Control 8, halved. Less round, as asked.\n  • color.surfaceRaised = #1d1e20  from fill #1d1e20 in Game Overlay. The dark grey asked for.\n\n$ gamestage theme from-draft td-4k2m9q7x1c3b\n$ gamestage theme publish kestrel-theme\n```\n\nThis chapter is for an organisation admin, at Monterosa or at a customer, who\nhas the customer's Figma file. If your agent already reads Figma and fills\n`tokens.json` itself, [make your organisation's theme](/docs/organisation#make-your-organisation-s-theme)\nby hand instead: both routes end at the same `theme publish`.\n\n## Before you start\n\n* **Be an organisation admin.** Drafts are your organisation's, and only the\n  people who may publish its themes may make them. Run `gamestage org admins`\n  to see who they are.\n* **Have the right frames.** Two to five game screens built from layers, such\n  as a question screen and a results screen. A phone mock-up that is one\n  flattened picture holds no colours or sizes, and is refused.\n* **Choose how to give the file.** A downloaded `.fig` needs no token. A Figma\n  link needs a personal access token that can read the file.\n\n## Draft from a downloaded .fig\n\nIn Figma, use File, Save local copy, then:\n\n```\ngamestage theme draft \"Kestrel Cup.fig\" --name kestrel\n```\n\nThe CLI reads the file on your machine and sends Gamestage only the values it\nfound: colours with how often each is used, type, corner radii, spacing, and\nthe variables by mode. It never sends the file, its pictures or its layers. If\nthe Save local copy item is missing, the file's owner has switched downloads\noff: ask them for the file, or use a link.\n\n## Draft from a Figma link\n\nCopy a link to the frame (Share, Copy link to selection), set your token in the\nenvironment, and draft:\n\n```\nexport FIGMA_API_TOKEN=<your token>\ngamestage theme draft \"https://www.figma.com/design/<key>/<name>?node-id=1-2\" --name kestrel\n```\n\nThe token goes to Figma and nowhere else. The CLI reads the frame on your\nmachine and sends Gamestage the same values a `.fig` gives.\n\nIn [Stage](https://gamestage.ai/stage/design-systems/drafts), you can paste a\nlink and a token instead. Gamestage then reads Figma on its side, uses the\ntoken for that one read and never stores, logs or forwards it.\n\n## Read the draft\n\nEach draft lists:\n\n* **Roles set from Figma**: one line per role, with the value, the Figma value\n  it came from and why.\n* **Values not used**: anything the model suggested that Gamestage UI has no\n  role for, that is in the wrong form, or that failed the theme check, with the\n  reason. These are never published. A value that fails a contrast check is\n  dropped and the library's own value stays.\n* **In the designs, with no role to take it**: what your screens have that no\n  component covers, such as a badge.\n* **Fonts the draft names**: families your designs use. A draft never declares\n  a font; see [publish it](#write-it-to-a-folder-and-publish-it).\n\n`--json` prints all of it, plus the theme check and what the model call cost.\n\n## Revise it in plain words\n\n```\ngamestage theme revise td-4k2m9q7x1c3b \"the answer buttons should be the dark grey from the Game Overlay frame, and less round\"\n```\n\nOnly the roles the words change are changed; every other role keeps its value\nand its reason. You can name a frame, because the draft keeps what each frame\nuses. A changed value that fails the theme check keeps the draft's earlier\nvalue, and says so.\n\n## Go back to an earlier revision\n\n```\ngamestage theme revise td-4k2m9q7x1c3b --to 1\n```\n\nGoing back makes a new revision with the earlier roles, so you can come forward\nagain the same way. Every revision is kept, and going back costs nothing\nagainst your organisation's limit.\n\n## See it on real components\n\nOpen the link the draft prints, or **Design systems**, then **Drafts**, in\n[Stage](https://gamestage.ai/stage/design-systems/drafts). The draft is drawn on\nreal Gamestage UI components: buttons, answers as a list in each state, a\nresults card, text and the colour roles. Load your font files there to see the\ndraft in them; they stay in your browser. Revise it in the **What should\nchange?** box.\n\n## Write it to a folder and publish it\n\n```\ngamestage theme from-draft td-4k2m9q7x1c3b kestrel-theme\ngamestage theme check kestrel-theme\ngamestage theme publish kestrel-theme\n```\n\n`from-draft` writes `theme.json` and `tokens.json`. It never writes into a\nfolder that already has a `theme.json`, so your fonts and declarations are\nnever overwritten. Before you publish, add your fonts to `theme.json` and their\nfiles under `fonts/`: see [ship your own font with your theme](/docs/organisation#ship-your-own-font-with-your-theme).\n`theme publish` then runs the same checks as always and asks you to declare\neach font.\n\n## Commands\n\n### `theme draft <figma-url | file.fig | export.json>`\n\n| Flag | What it does |\n| --- | --- |\n| `--name <name>` | The theme's name: 3 to 40 lowercase letters, numbers and hyphens. Default: from the Figma file's name. |\n| `--org <id>` | Draft as this organisation for this command only, when you are its admin. |\n| `--json` | Print the draft as JSON. |\n\nExit 0 when the draft passes the theme check, 1 when it does not or was\nrefused, 2 when the file or link could not be read.\n\n### `theme revise <draft> [\"<instruction>\"]`\n\n| Flag | What it does |\n| --- | --- |\n| `--to <revision>` | Go back to an earlier revision instead of giving an instruction. |\n| `--org <id>` | Work as this organisation for this command only. |\n| `--json` | Print the new revision as JSON. |\n\n### `theme drafts`\n\n| Flag | What it does |\n| --- | --- |\n| `--org <id>` | List this organisation's drafts for this command only. |\n| `--json` | Print the list as JSON. |\n\n### `theme from-draft <draft> [dir]`\n\n| Flag | What it does |\n| --- | --- |\n| `--revision <n>` | Write this revision rather than the latest. |\n| `--version <version>` | The version written in `theme.json`. Default `0.1.0`. |\n| `--org <id>` | Work as this organisation for this command only. |\n| `--json` | Print what was written as JSON. |\n\n## What Gamestage sees, and what it keeps\n\n* **From the CLI**, Gamestage receives the values the file holds and nothing\n  else: no file, no pictures, no token.\n* **From Stage**, a `.fig` is read on Gamestage's side and deleted when the\n  request ends. A link's token is used for that one read and is never stored,\n  logged, put in the draft or sent to the model.\n* **The draft is kept privately for your organisation**, beside its published\n  themes: the values the model was shown, and every revision. Only your\n  organisation's admins can read it, and Monterosa only processes it.\n* **The model** runs through OpenRouter, on hosts that keep no data and are not\n  in China. It is shown the values and the role list, never a token.\n\n## Limits\n\n| Limit | Value |\n| --- | --- |\n| Drafts and revisions per organisation | 20 an hour, 100 a day. Going back is free. |\n| Drafts kept per organisation | 200 |\n| Revisions per draft | 30 |\n| Instruction | 1,000 characters |\n| `.fig` sent from Stage | 3 MB. The CLI reads any size on your machine. |\n| export.json | 4 MB |\n\n## When it fails\n\nEach refusal says what went wrong and what to do. The common ones:\n\n| Code | What happened | What to do |\n| --- | --- | --- |\n| `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. |\n| `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. |\n| `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. |\n| `token_missing`, `figma_token_rejected` | No token, or Figma rejected it. | Make a personal access token in Figma that can read files. |\n| `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. |\n| `fig_too_large` | A `.fig` sent from Stage is over 3 MB. | Run `gamestage theme draft <file.fig>`, or use a link. |\n| `draft_limit` | Your organisation reached its hourly or daily limit. | Try again at the time the message gives. |\n| `model_busy`, `model_timeout` | The model was busy or slow. | Try again; choose fewer frames if it keeps happening. |\n| `drafts_unavailable`, `model_unavailable` | Drafts are not switched on where you are working. | Tell Monterosa. |\n| `theme_exists` | `from-draft` was pointed at a folder that already has a theme. | Choose another folder. |\n"}