Skip to main content

Figma Variables — Troubleshooting

Goal: Help designers quickly identify and solve common problems with tokens, variables, and exports. Use this guide whenever something doesn’t look right in your Figma files or exported libraries.

Fast Fixes

Variable didn’t appear
→ Check token type compatibility; composite/asset/composition are skipped as Variables. Export as a Style instead.

Value didn’t update
→ You exported the wrong sets/modes or updated a primitive but the brand var is hard‑coded. Re‑alias brand var to primitive.

AUTO/percent failed
→ Convert to numeric, or rely on Styles for automatic behaviors.

Mode switch looks wrong
→ Check aliases per mode; ensure your collection has the mode values defined.

Unexpected overwrites
→ Revert to previous file version, scope export narrowly, and re‑export in the correct order.

1. Quick Troubleshooting Flow​

Is the problem with…
↓ Tokens Studio → Export → Figma Variables → Component Binding → Mode Switch → Library Publish

Start at the top of the chain:

  1. Tokens are correct?
  2. Export worked?
  3. Variables applied correctly?
  4. Modes and brands switch correctly?
  5. Library publish and PR match changes?

Start at the top of the chain:

  1. Tokens are correct?
  2. Export worked?
  3. Variables applied correctly?
  4. Modes and brands switch correctly?
  5. Library publish and PR match changes?

2. Common Issues and Fixes​

ProblemLikely CauseSolutionExample
Variable missing in Figma after exportToken type unsupported for direct variable export (e.g., typography object, shadow, gradient).Export as Style with variable references instead.Typography H1 object → Export as Text Style referencing: gb.font-size.24
Mode switching doesn’t workAlias chain is broken or a mode value is missing.Check that both Light/Dark modes are defined in gb.colours.grey. Verify alias points correctly downstream → upstream.gb.colours.grey.5 (Light) ↔ gb.colours.grey.110 (Dark)
Brand override not appliedExport order incorrect. Brand tokens exported before primitives.Re-export following order: 1. Primitives → 2. Brand → 3. Semantic.gb.colours.blue.40 must exist before betfair.gb.colours.button.bg.
Unexpected overwrites during exportToo many token sets selected during export.Narrow scope to only the sets you intend to update. Export into a scratch file first if unsure.Selected “All Brands” when only Betfair was needed.
Figma shows raw HEX values instead of variable namesComponent not bound to variables, still using fixed values.Replace all fills, typography, spacing with variable bindings.❌ #FFCE2E → ✔ {sm.color.action.bg}
Line height not exportedAUTO values aren’t supported for number variables.Use numeric values or manage via Text Styles.❌ "AUTO" → ✔ 24
Opacity or percentages don’t exportFigma Variables require unitless decimal values.Convert percentages to decimals.❌ 50% → ✔ 0.5
Gradient doesn’t appear as a variableGradients are not supported.Export color stops as separate variables, then assemble gradient manually and create a style.gb.colours.gradient.sbg-01 split into individual stop colors.

3. Mode & Brand Switching Issues​

CheckHow to Fix
Are both light and dark values defined?Verify under gb.colours.grey: - Light → gb.colours.grey.5 = #FCFCFD - Dark → gb.colours.grey.110 = #18181A
Is the brand alias pointing to a primitive?Example: betfair.gb.colours.button.bg → gb.colours.blue.40
Was the export order correct?Primitives → Brand → Semantic
Did you test with multiple brands in Figma?Place Betfair and Sky buttons side-by-side to confirm correct fallback.

4. Fallback Chain Breaks​

If a brand or product token is missing, the fallback must cascade safely to the next available layer.

Example Broken Chain:

`sm.color.action.bg → betfair.gb.colours.button.bg` → ❌ MISSING

How to Fix:​

Create or restore the missing primitive token:

`gb.colours.blue.40 = #185FD8`

Re-alias the brand token to point to it:​

`betfair.gb.colours.button.bg` → `gb.colours.blue.40`

Verify the semantic token points to the brand token:​

`sm.color.action.bg` → `betfair.gb.colours.button.bg`

5. Export Problems​

ProblemSolution
Export fails entirely- Confirm you’re on the correct branch in TS. - Restart Tokens Studio plugin. - Ensure file permissions allow variable creation.
Variables created but values missing- Check token type compatibility. - Ensure primitive tokens exist before aliases.
Styles missing after export- Enable "Create Styles with variable references" option in TS export panel.

6. QA Debugging Checklist​

Before publishing a library, run this debug checklist:

CategoryChecklist ItemPass/Fail
BindingsNo raw HEX or pixel values in components.⬜
ModesLight/Dark switch updates all surfaces correctly.⬜
BrandsBetfair, Sky, Paddy Power all switch correctly.⬜
FallbacksMissing brand/product values fall back to primitives.⬜
CollectionsVariables are in the correct Figma collection (00-Primitives, 10-Brand, 40-Semantic).⬜
AliasesAliases point downstream → upstream.⬜

7. Visual Debug Map​

Workflow Visualization:
Tokens Studio ↓ Figma Variables ↓ Components (bound to variables) ↓ Mode & Brand Switching ↓ QA & Publish

  • Problem at top → Fix in Tokens Studio.
  • Problem in middle → Check export and variable bindings.
  • Problem at bottom → QA issues with modes or brand overrides.

8. Example Debug Scenario​

Scenario: Sky brand button isn’t updating when switching from Betfair.

Debug Path:​

1. Check the token in Tokens Studio:

sky.gb.colours.button.bg → gb.colours.blue.40

✅ Correct alias found.

2. Check export order: - Did you export Primitives first? - gb.colours.blue.40 must exist before the Sky alias.

3. Check the component binding: - Button background should reference: `{sm.color.action.bg}`

4. Test fallback: - If Sky token is missing, it should fall back to the primitive token.

9. Last-Resort Actions​

If nothing else works:

  • Revert to previous version of the library in Figma (File → Version History).
  • Export into a scratch Figma file to isolate the issue.
  • Remove and re-add only the impacted collections.
  • Ask a reviewer to check PR JSON for mismatches.

10. Summary​

  • Most issues start in Tokens Studio, so check tokens first.

  • Export order matters:

    Variables

    1. Agnostic
    2. Brand Sequence
    3. Semantic

    Styles

    1. Typography
    2. Effects

  • Bindings are critical: replace all raw values with variable references.

  • Fallback chains keep the system stable: never leave gaps between layers.

  • Use the QA checklist before every publish to catch problems early.