Overview
Variflow Tokens brings your design tokens into ExpressionEngine 7. Your token file (W3C DTCG
format) lives in your repo. Variflow checks it, compiles it to one stylesheet, and gives editors
pickers that only offer your tokens: a section's look ("Light", "Dark") or a single colour or
spacing step. Entries store a reference such as scheme:dark, never a hex code. Change the token
file, build, and every entry follows.
What's in it
- Builds:
- checks the token file (missing references, loops, unknown types, contrast) and compiles it to a hashed stylesheet;
- publishes only when there are no errors, so a bad file never replaces the live CSS;
- lets you roll back to an earlier build.
- The Tokens fieldtype:
- scheme cards, colour swatches, spacing steps or a dropdown;
- works in Grid and Fluid;
- outputs CSS variables (
var(--vf-…)) or a scheme attribute (data-vf-scheme="dark").
- Usage tracking: every stored reference is indexed. A build that would remove a token content still uses stops and says where it's used.
- Changing tokens safely: rename and deprecate with a patch to commit, an optional rewrite of stored entries, and remapping of removed tokens.
- Retrofitting:
- turn an existing stylesheet's custom properties into a draft token file;
- convert Text Input, Select, Radio and Color Picker fields to Tokens fields, with a review of every value and Undo.
- Framework maps: a Bootstrap 5.3 preset sets Bootstrap's own variables from your tokens.
- Grid and layout presets: define the grid (columns, gutter, containers, breakpoints) and
layout presets in the token file; an opt-in layout stylesheet renders them, with their reflow,
from a
data-vf-layoutattribute. Grid and layout presets - Component variants: named looks for a component (a button's Primary, Outline and Ghost) that editors pick by name. Each is right under every scheme, and contrast is checked per variant. Component variants
- Command line: build, verify, roll back, import, convert and more, for deploy scripts. A
variflow:doctorcommand checks your set-up. - Integration API for add-on developers: other add-ons can offer Variflow's picker, output tokens as Tokens fields do, and register their own storage so usage tracking, the build guard, renames and remaps cover it. Developers
Requirements
- ExpressionEngine 7.3 or later.
- PHP 8.2 or later, with the json, mbstring and ctype extensions (standard on most hosts).
- The database ExpressionEngine 7 itself needs (MySQL or MariaDB). Variflow adds seven tables.
- Optional: Bloqs 5, for Tokens atoms in blocks.
- Shell access to run EE's command line is recommended for deploys, but not required: the control panel can build too.
The guide
- Getting started: install, a token file, a build, your first field.
- Token files: the format, Variflow's extensions, schemes, base files and MSM.
- The Tokens fieldtype: settings, what editors see, Grid and Fluid.
- Templates: the CSS tag, values, field tags and schemes in markup.
- The control panel: each page, and who can do what.
- Changing tokens: rename, deprecate, the rewrite queue and remap.
- Retrofitting a site: import from CSS, field conversion, framework maps.
- Deploying: builds in deploy scripts, auto-build, rollback, environments.
- Command line: every command, its options and exit codes.
- Troubleshooting: start with
variflow:doctor.
For add-on developers: Developers, the Integration API (Variflow's picker, template output and usage tracking for content your add-on stores).
The same guide is in the control panel under Add-Ons › Variflow Tokens › Docs.
Licensing
One licence covers one production site, plus any number of development and staging copies of it. Buy it in the ExpressionEngine store, then add its key in Add-Ons › Licences (EE checks it automatically; the status refreshes the next time someone loads a control panel page).
A 14-day trial. On a production site without a valid licence, everything works for 14 days, counted from the first time Variflow sees the problem (a new site, or a renewal that lapsed; adding a key resets it). Members who can act on it (super admins, and roles with access to the add-on) see a banner on Variflow's pages counting down the days; they can dismiss it for the browser session.
After the trial, a few configuration and import tools stop until a licence is added. Nothing a live site, a deploy or an editor depends on ever stops:
| Always works | Stops after the trial, without a licence |
|---|---|
| Builds, verify and rollback (CLI and control panel), and builds a deploy triggers | Saving Settings |
| Template tags and field output | Rename and deprecate |
| The Tokens fieldtype and pickers for editors | Import: downloading, saving or using the token file |
| Every control panel page (Tokens, Schemes, Builds, Settings, Docs) | Field conversion: Convert |
Remap, the rewrite queue, variflow:rewrite:run |
variflow:import, variflow:import:tokens and variflow:convert: writing anything |
| Import's review; Field conversion's review and dry run | |
| Finishing or undoing a field conversion | |
variflow:build, variflow:usage:rebuild, variflow:doctor |
Only EE's statuses that name Variflow as unlicensed (invalid, expired) count. EE's own
licence messages about your ExpressionEngine installation (such as update_available or
license_expired) never count against Variflow, and neither does "no status" (na).
Development hosts are always treated as licensed: localhost, 127.0.0.1, *.test,
*.local, *.localhost, *.ddev.site, *.lndo.site, and any you add in config.php:
$config['variflow_dev_domains'] = ['staging.example.com']; // and its subdomains
$config['bison_dev_domains'] = ['*.preview.example.com']; // shared by Bison Digital add-ons
To see what an unlicensed site gets on a development host, set
$config['variflow_simulate_license'] = 'grace'; (the trial's banner) or 'lapsed' (after the
trial). It can only take a licence away, never grant one.
The full terms are in LICENSE.md. Variflow's editor components use Lit (LICENSE-lit.txt).
Support
- This guide online: gobison.digital/documentation/variflow.
- Help and questions: gobison.digital/support or jon@gobison.digital.
- Version history: CHANGELOG.md.
- Before you ask for help, run
php system/ee/eecli.php variflow:doctorand include its output.
Variflow Tokens is made by Bison Digital.