From Figma, Tokens Studio or Sketch
Your design system already lives in Figma, as variables with modes (Light, Dark, Brand…), or in Tokens Studio, as token sets and themes. Variflow calls modes schemes. Import turns an export into a token file with one scheme per mode: export, import, build, with no JSON to edit by hand.
Variflow never connects to Figma. You export the files and give them to Variflow.
Sketch's token export imports too; see From Sketch.
1. Export
From Figma
-
Open the Variables panel (Local variables).
-
Right-click the collection that has your modes, for example Theme with Light and Dark, and choose Export modes. Figma writes one
.tokens.jsonfile per mode, for exampleLight.tokens.jsonandDark.tokens.json. To export a single mode instead, right-click the mode and choose Export mode. -
Do the same for the collections those variables point at (your primitives), or a reference to them can't be kept.
-
Put each collection's files in a folder named after the collection:
figma-export/ Primitives/Value.tokens.json Theme/Light.tokens.json Theme/Dark.tokens.jsonFigma doesn't write the collection's name into its files, so Variflow takes it from the folder. Each file's mode comes from the file itself (Figma writes it as
$extensions["com.figma.modeName"]), or from its name.
Variables plugins that write DTCG files, one per mode, work the same way.
From Tokens Studio
Either of these works:
- One file: export or sync to a single JSON file. It holds your token sets,
$themesand$metadata. - A folder: sync to a folder (GitHub, GitLab, a local folder) with multi-file storage. It
holds a
.jsonfile per token set, plus$themes.jsonand$metadata.json. Import the whole folder, or a zip of it in the control panel.
Each theme is a mode, and a theme group is a mode group. A theme's tokens are its token
sets marked Enabled or Source, in your token set order, later sets winning. Both the
legacy format (value, type) and the W3C DTCG format ($value, $type) are read.
From Sketch
In the Sketch web app, open the document or Library, choose Document details › Export Design Tokens, pick JSON and download it. Import that one file; color variables, text styles and their colours arrive as tokens. Sketch has no modes, so groups such as "Light Mode" and "Dark Mode" import as ordinary groups, not schemes.
Expect a few warnings in the review:
- Names: Sketch names keep their spaces ("Dark Mode"), which Variflow names can't have, so
they become
Dark-Mode. Labels keep the original wording. - Line height: Sketch writes
0for an Auto line height. It's left out, so the browser's normal line height applies, rather than becomingline-height: 0. - Font names: Sketch writes PostScript names, such as
TimesNewRomanPSMTorInter-Bold. Change them to the family name your CSS loads (Times New Roman,Inter).
Layer styles (fills, borders, shadows) aren't imported yet. Make colour, border and shadow tokens for them by hand.
From a DTCG resolver document
The DTCG 2025.10 Resolver Module describes
sets and modifiers in a .resolver.json file. Import that file together with every file it refers
to. Sets are shared by every mode; one modifier's contexts become the schemes, and its default
is the default mode unless you pick another. Remote $ref URLs aren't fetched: download them
and import them with the rest.
2. Import
In the control panel: Add-Ons › Variflow Tokens › Import › Design tokens (super admins).
Upload the .json files, or a .zip of the export folder. The limit is 1 MB a file and 2 MB in all.
If you keep an extras file for what the export can't carry, choose it under
Extras file (optional). Then:
- Pick which group's modes become schemes, if the export has more than one group.
- Pick the default mode.
- Read the preview: each scheme's name, label and number of overrides, then what was skipped and any warnings.
- Review what was inferred: labels, tiers, contrast pairs and derive rules (see What's inferred). Turn a kind off or untick items, then Update preview. With an extras file, Added from … lists what it added, and any entry left out, with why.
- Save draft writes it, with what's ticked, next to your token file. Download gives you the file instead.
- On a site with no token file yet, the saved draft's banner offers Use as the token file: it
renames
site.tokens.import.jsontosite.tokens.jsonand links to Rebuild from file. It never replaces a token file, so the button isn't there when you have one.
On the command line:
php system/ee/eecli.php variflow:import:tokens figma-export --default=Light
php system/ee/eecli.php variflow:import:tokens tokens.json --schemes-from=Mode --default=Light
php system/ee/eecli.php variflow:import:tokens figma-export --default=Light --extras=brand.variflow-extras.json
This writes site.tokens.import.json next to your token file and prints the review, with what
was inferred. Add --no-pairs (or --no-labels, --no-tiers, --no-derive) to leave a kind out. See
Command line for every option.
On a site with no token file yet, add --use-as-token-file to make the draft the token file once
it's written, or run variflow:import:tokens --use-as-token-file on its own to use the draft
you've already saved. Either is refused when the site has a token file.
The import never replaces your live token file. Reviewing works without a licence; saving, downloading or writing the draft needs one after the 14-day trial (Licensing).
3. Check it, then swap it in
php system/ee/eecli.php variflow:verify --file=system/user/config/tokens/site.tokens.import.json
This checks the draft against your site's content without using it. A token your entries use that the draft doesn't have is reported, for example. Then (if you didn't use it as the token file already):
- Replace your token file with the draft, or point
variflow_tokens_fileat it. - Commit it.
- Run
variflow:build.
What becomes a scheme
- The base: the default mode's tokens, plus everything every mode shares (usually your
primitives), make up the file's tokens.
defaultSchemeis that mode. - The schemes: each other mode becomes a scheme. Its name is the mode's name as a slug, so
"Dark · night forest" becomes
dark-night-forest, and its label is the mode's name. - Overrides: a scheme holds only the tokens whose value differs from the default mode.
References stay references (
{color.fern.950}) and are never resolved to values. - Figma's links to other collections: Figma exports a variable that points into another
collection as a value, plus
com.figma.aliasData. When the target is in the import, it is written as a reference again. - Tokens some modes lack:
- A token that isn't in the default mode joins the base from the first mode that has it, with a warning.
- A token missing from another mode keeps the default's value in that scheme.
- Names: a name Variflow can't use, such as "Brand Name", is changed ("Brand-Name"), and the references to it follow. Each change is listed.
In every scheme, each token resolves to the value it had in that mode.
Several mode groups
Variflow's schemes are one dimension. If the export has two mode groups, say colour (Light, Dark) and density (Comfortable, Compact), you pick the group that becomes schemes.
- Every other group uses one mode: its first, or the one you pick (
--use=Density:Compact). - The review lists what was left out, for example "Density: Compact, where 2 tokens differ from Comfortable".
- On the command line, an export with several groups and no
--schemes-fromlists the groups and exits 2 without writing. So does a missing--default.
A group with only one mode, such as a Figma primitives collection, is simply shared.
What's skipped
Nothing is dropped silently. The review lists each skipped token and the reason:
- Unsupported types: for example Figma's string and boolean variables, or Tokens Studio's
assetandtexttypes. You get the same warning as in a token file. - Tokens Studio math: a value such as
{space.base} * 2. - Type clashes: a token whose
$typediffers between modes. - Broken references: a token that refers to a skipped or missing token.
- Values that aren't tokens: an object with fields but no
$value(orvalue), such as a style written as{"fontSize": 32, "type": "typography"}. It's named with its fields, so you can move them under$valueand import again.
The import keeps:
$description, Tokens Studio'sdescriptionincluded;- every
$extensionsblock, Figma's (com.figma.variableId, scopes,hiddenFromPublishing) included. Variflow ignores them; - hidden and scoped Figma variables, which aren't filtered out.
Typography is tidied as it comes in, each change listed as a warning:
- Line heights become ratios, as CSS and DTCG expect:
40or40pxon a 32px font becomes1.25, and150%becomes1.5. A plain number of 3 or less is already a ratio and is kept. A line height that can't become a ratio (pixels on aremfont size, say) and Sketch's0for Auto are left out. - Fields a typography token has no place for, such as
color,textTransformandtextAlign, are left out. Make a colour token for a text colour.
Figma's number variables arrive as number tokens, without units. Give spacing tokens a unit
afterwards if you want px or rem.
What's inferred
An export has no place for editor labels, tiers, contrast pairs or hover rules. Variflow infers
them from how your tokens are named and organised, and writes them into the draft. The review lists
each one with its reason ("on-primary sits on primary", "12% toward black in every mode, ΔE ≤ 0.4").
In the control panel, each kind has a switch and each item a tick box; Save draft writes only
what's ticked. On the command line, turn a kind off with --no-labels, --no-tiers, --no-pairs
or --no-derive; --json lists every proposal.
Nothing your export already says is replaced: a token that has a label, tier or derive rule keeps it. Nothing is inferred from colour values alone: every rule needs a naming signal.
Labels
Every token without a label gets $extensions.variflow.label, written out so it's easy to edit:
the readable name editors would see anyway ("Surface default", from the last two parts of the
name). When a name had to change on import ("Brand Name" became Brand-Name), or is written
in camelCase (primaryHover), the label keeps its words ("Brand Name", "Primary hover").
Tiers
In this order:
- A collection, set or group named like a tier:
primitive(s),base,core,paletteare primitive;semantic,alias(es),theme,systemare semantic;component(s)is component. For Figma that's the collection's folder (Primitives/Value.tokens.json), for Tokens Studio the token set (core,semantic/light), for a resolver document the set or modifier. - A derived colour (see Derive rules below) is semantic.
- A component-like path (
button.…,card.…,input.…,nav.…, orcolor.button.…) whose tokens refer to semantic ones is component. - A plain value that's the same in every mode is primitive.
- A reference, or a value that differs between modes, is semantic.
The tier goes on the highest group whose tokens all agree, and on single tokens otherwise. The review counts the tokens per tier and per reason.
Contrast pairs
| Convention | Pairs with | Rule |
|---|---|---|
on-X or onX (action.on-primary, fg.on-brand) |
X, and its -hover, -pressed, -active and -focus shades |
text |
text, fg, foreground, content, icon |
each surface in the same family | text |
status colours: success, warning, danger, error, info, feedback… |
each surface in the same family | text |
border, divider, stroke, focus, ring |
each surface in the same family, except the background a border outlines (below) | ui |
an action colour (action, primary, secondary, brand, accent…) that has an on- colour |
the default surface | ui |
| an action colour without one, so it's used as text | each surface in the same family | text |
- Surfaces are names with
surface,background,bg,canvas,containerorfill. - The family is the name before the role word:
colorincolor.text.default,buttoninbutton.text. When a family has no surfaces, the nearest family above it is used. - Inverse: a name with
inversepairs only with inverse surfaces, and the others never do. - At most 6 surfaces per colour, the closest names first: same group, then the same last part
(
text.defaultwithsurface.default), thendefault. The rest are listed. - A border isn't paired with the background it outlines: one in its own group
(
component.card.borderwithcomponent.card.background, and that background's hover and pressed shades), or one it takes its colour from in every scheme (a filled button whose border is{color.action.primary}, like its fill). The contrast that makes such a border visible is against what's around the component, which the names don't say. A whole-palette group such ascolordoesn't count as one thing's group, socolor.borderstill pairs withcolor.background. Focus rings are always paired. The review lists the backgrounds left out. - Kept: only pairs of two colours that every mode has. Palette steps (
blue.500) and tokens in a primitive collection are never paired. - Checked: each pair in every scheme, with the same contrast check as a build. The review shows
its worst ratio and the scheme. A failing pair is kept and flagged, not dropped or "fixed": it's
the finding.
variflow:verifyreports it as a warning.
Derive rules
A hover or pressed shade arrives from a design tool as a plain value in each mode. Variflow turns it back into a derive rule when one rule reproduces it everywhere.
- Candidates: a colour whose last part is
hover,pressed,active,focus,subtle,muted,strongoremphasis, or ends with one (primary-hover,primaryHover). - Its base: the name without the state (
primary-hover→primary), else the group above it (button.background.hover→button.background), else adefaultorbasebeside it. - The fit: a mix toward
black,whiteortransparentinoklab,oklchorsrgb, with one amount in whole percents, within ΔE 1.0 (OK ΔE) in every mode. ΔE 1 is about the smallest difference anyone notices side by side; the export's 8-bit colours and the rounding to a whole percent take up most of it. - Black in some modes, white in others: the rule mixes toward
color.mix.target, one semantic token that's black or white per scheme. Your export's owncolor.mix.targetis used if it has one; otherwise the import adds it. - When it fits, the token gets
$extensions.variflow.derive, its scheme overrides go (the rule covers every scheme), and$valuekeeps the default mode's value as a fallback. - Every value is checked again after the rules are written. A rule that would move any token's value by more than ΔE 1.0 in any scheme isn't written.
A shade that's a reference ({color.fern.800}) in every mode stays a reference: it's a palette
choice, not a mix.
What's left to you
The review lists, per kind, what wasn't inferred and why. Typically:
- A shade with no base by its name, such as
outline-hoverwhen there's nooutline. - A hover made by hand, whose amount differs between modes ("10% toward black in Light, 30% toward white in Dark") or that no mix reproduces within ΔE 1.0. Its plain values stay.
- Translucent colours and shadows named without a state word (
overlay.scrim,shadow.soft): kept as plain values and, being the same in every mode, primitive. - Pairs no convention reveals, and the surfaces past the 6 per colour.
Scheme labels come from the mode names. Add a description under $extensions.variflow.schemes
if you want one, or keep labels, descriptions and the rest in an extras file,
so every import gets them back. Your next export can be imported the same way; compare the new
draft with your token file before you swap it in, so you keep what you edited by hand.
The extras file
Figma and Tokens Studio have no place for some of what a Variflow token file holds: grid layout
presets, component variants, scheme labels and descriptions, group descriptions, flags such as
hidden, and the contrast pairs you've chosen. Keep them in a small JSON file beside the export
and give it to the import with the export, as the CP's Extras file or --extras=<file>. The
import merges it in before the review, so the draft you save already has them.
{
"variflowExtras": 1,
"description": "Fernhaven Outfitters: the Variflow Tokens demo set.",
"schemes": {
"dark": { "label": "Dark · night forest", "description": "Footers, evening trips." }
},
"groups": {
"grid": {
"variflow": {
"presets": [
{ "name": "full", "label": "Full width", "spans": [12] },
{ "name": "8/4", "label": "Wide and narrow", "spans": [8, 4] }
]
}
},
"color.illustration": {
"description": "Duotone photo placeholders. Not offered to editors.",
"variflow": { "hidden": true }
},
"component.button": {
"variflow": {
"defaultVariant": "primary",
"variants": {
"primary": { "label": "Primary", "overrides": {} },
"outline": {
"label": "Outline",
"overrides": {
"component.button.background": "{color.surface.default}",
"component.button.text": "{color.action.secondary}"
}
}
}
}
}
},
"tokens": {
"color.mix.target": { "variflow": { "hidden": true } }
},
"contrastPairs": [
{ "fg": "color.text.default", "bg": "color.surface.default", "rule": "text" },
{ "fg": "color.focus.ring", "bg": "color.surface.raised", "rule": "ui" }
]
}
Every key is optional.
| Key | What it adds |
|---|---|
variflowExtras |
The format's version, 1. Recommended, so the file says what it is. |
description |
The token file's $description. |
schemes |
Per scheme, its label and description. A scheme is named by its name (dark) or its mode's (Dark), in any case. |
groups |
Per group (a dotted path), its description and variflow: what goes in the group's $extensions.variflow, such as presets, variants, defaultVariant or hidden. |
tokens |
Per token, the same: description, and variflow for its $extensions.variflow (hidden, a label…). |
contrastPairs |
The pairs to check, as in a token file: fg, bg and rule (text or ui; text when left out). |
- Merged over what the import wrote: a
labelhere replaces the inferred one; keys you don't give are left as they are. - Contrast pairs replace inference. When the file has
contrastPairs(even an empty list), the import writes exactly those and infers none. Each is checked in every scheme, and the review shows its worst ratio, as it does for inferred pairs. - Conflicts are left out, and say so. An entry naming a scheme, group or token the import doesn't have (renamed in Figma, say) isn't written; its line in the review shows a warning with the reason. So is an entry that would stop the draft validating. The rest is still written.
- What isn't an extras file is refused with the reason: a key other than those above (or
$commentand$schema, which are ignored), or a value of the wrong shape. Uploading the export itself as the extras file is the usual slip. - The draft notes the file's name in
$extensions.variflow.import.extras.
To start one from a token file you already have, copy those parts out of it: the scheme labels and
descriptions from $extensions.variflow.schemes, each group's $description and
$extensions.variflow (leave out label and tier, which the import infers), token flags such as
hidden, and $extensions.variflow.contrastPairs.