Figma Variables — Guidelines
Goal: Define clear rules and best practices for creating, exporting, and managing variables so our design system stays scalable, consistent, and easy to maintain.
Export Order
To keep alias chains clean and predictable, always export in this order:
- Primitives (00-global/base)
- Brand Tokens (00-global/betfair, 00-global/sky, etc.)
- Semantic Tokens (01-semantic)
- Product/Platform overrides (if applicable)
Guardrails to avoid unwanted updates
| Do | Don’t |
|---|---|
| Export primitives first, then brand tokens. | Export brands before primitives. |
| Work in a scratch Figma file when testing. | Test exports directly in production libraries. |
| Alias brand variables to primitives. | Hard-code brand values without linking to primitives. |
| Snapshot the library file before major updates. | Overwrite variables without version history. |
| Use clear changelogs when publishing libraries. | Publish changes without documentation. |
Common Issues & Fixes
| Issue | Likely Cause | Solution |
|---|---|---|
| Variable doesn’t appear in Figma | Token type not supported for Variables. | Export as Style with variable reference. |
| Light/Dark switch broken | Missing alias chain between modes. | Verify gb.colours.grey mapping. |
| Brand overrides not showing | Export order incorrect. | Export primitives first, then brand. |
| Overwritten values | Export scope too broad. | Limit export to only relevant token sets. |
Summary
- Always start with primitives, then alias upwards.
- Follow strict naming patterns for clarity and automation.
- Use collections and modes carefully to support brand and platform scaling.
- Perform QA and changelogs before publishing.
- The health of our multi-brand system depends on consistent structure and disciplined exports.