Docs /Variflow Tokens

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

  1. Open the Variables panel (Local variables).

  2. Right-click the collection that has your modes, for example Theme with Light and Dark, and choose Export modes. Figma writes one .tokens.json file per mode, for example Light.tokens.json and Dark.tokens.json. To export a single mode instead, right-click the mode and choose Export mode.

  3. Do the same for the collections those variables point at (your primitives), or a reference to them can't be kept.

  4. 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.json
    

    Figma 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, $themes and $metadata.
  • A folder: sync to a folder (GitHub, GitLab, a local folder) with multi-file storage. It holds a .json file per token set, plus $themes.json and $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 0 for an Auto line height. It's left out, so the browser's normal line height applies, rather than becoming line-height: 0.
  • Font names: Sketch writes PostScript names, such as TimesNewRomanPSMT or Inter-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:

  1. Pick which group's modes become schemes, if the export has more than one group.
  2. Pick the default mode.
  3. Read the preview: each scheme's name, label and number of overrides, then what was skipped and any warnings.
  4. 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.
  5. Save draft writes it, with what's ticked, next to your token file. Download gives you the file instead.
  6. On a site with no token file yet, the saved draft's banner offers Use as the token file: it renames site.tokens.import.json to site.tokens.json and 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):

  1. Replace your token file with the draft, or point variflow_tokens_file at it.
  2. Commit it.
  3. 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. defaultScheme is 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-from lists 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 asset and text types. 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 $type differs 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 (or value), such as a style written as {"fontSize": 32, "type": "typography"}. It's named with its fields, so you can move them under $value and import again.

The import keeps:

  • $description, Tokens Studio's description included;
  • every $extensions block, 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: 40 or 40px on a 32px font becomes 1.25, and 150% becomes 1.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 a rem font size, say) and Sketch's 0 for Auto are left out.
  • Fields a typography token has no place for, such as color, textTransform and textAlign, 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:

  1. A collection, set or group named like a tier: primitive(s), base, core, palette are primitive; semantic, alias(es), theme, system are 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.
  2. A derived colour (see Derive rules below) is semantic.
  3. A component-like path (button.…, card.…, input.…, nav.…, or color.button.…) whose tokens refer to semantic ones is component.
  4. A plain value that's the same in every mode is primitive.
  5. 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, container or fill.
  • The family is the name before the role word: color in color.text.default, button in button.text. When a family has no surfaces, the nearest family above it is used.
  • Inverse: a name with inverse pairs 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.default with surface.default), then default. The rest are listed.
  • A border isn't paired with the background it outlines: one in its own group (component.card.border with component.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 as color doesn't count as one thing's group, so color.border still pairs with color.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:verify reports 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, strong or emphasis, 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 a default or base beside it.
  • The fit: a mix toward black, white or transparent in oklab, oklch or srgb, 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 own color.mix.target is 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 $value keeps 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-hover when there's no outline.
  • 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 label here 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 $comment and $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.

Related