Docs /Variflow Tokens

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-layout attribute. 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:doctor command 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

  1. Getting started: install, a token file, a build, your first field.
  2. Token files: the format, Variflow's extensions, schemes, base files and MSM.
  3. The Tokens fieldtype: settings, what editors see, Grid and Fluid.
  4. Templates: the CSS tag, values, field tags and schemes in markup.
  5. The control panel: each page, and who can do what.
  6. Changing tokens: rename, deprecate, the rewrite queue and remap.
  7. Retrofitting a site: import from CSS, field conversion, framework maps.
  8. Deploying: builds in deploy scripts, auto-build, rollback, environments.
  9. Command line: every command, its options and exit codes.
  10. 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

Variflow Tokens is made by Bison Digital.