Getting started
From a fresh install to a section whose colours come from your tokens, in about twenty minutes. Nothing on your live pages changes until you add the CSS tag in step 5.
The commands below run EE's command line from your site's root folder:
php system/ee/eecli.php <command>
On a local stack, run it where the site's PHP runs: ddev exec php system/ee/eecli.php … on
DDEV, lando php system/ee/eecli.php … on Lando, or inside your PHP container on Docker
Compose. Everything here can also be done in the control panel, except writing a starter file
(step 2), which you can do by hand.
Requirements
- ExpressionEngine 7.3 or later, PHP 8.2 or later.
- Write access to
system/user/config/(for the token file) andthemes/user/(for the built CSS).
1. Install
-
Unzip the download. It has two folders,
system/user/addons/variflowandthemes/user/variflow. Copy each into the same place in your site. -
In the control panel, open Add-Ons, find Variflow Tokens and click Install. Or:
php system/ee/eecli.php addons:install -a variflow -
Check the set-up:
php system/ee/eecli.php variflow:doctorAt this point it warns that there's no token file and no live build. Everything else should say
ok.
2. A token file
Pick one:
-
See everything working first: the demo set is Fernhaven Outfitters, an outdoor shop: seven colour ramps, five schemes (Light, Dark, Brand, Muted, Seasonal), hover and pressed shades derived per scheme, translucent tokens for shadows and scrims, and 23 contrast pairs checked in every scheme.
php system/ee/eecli.php variflow:init --demo -
Start small: a starter file with a few colours, spacing steps and two schemes.
php system/ee/eecli.php variflow:init -
You already use CSS custom properties: turn them into a draft token file with Add-Ons › Variflow Tokens › Import. See Retrofitting a site.
-
You have a file from a design tool: any W3C DTCG token file works, and so does a Tokens Studio export. See Token files.
variflow:init writes system/user/config/tokens/site.tokens.json and prints the
config.php lines for it. With the default location you don't need them, but adding them makes
the setup visible to the next developer:
$config['variflow_tokens_file'] = 'system/user/config/tokens/site.tokens.json';
$config['variflow_prefix'] = 'vf';
$config['variflow_output_dir'] = 'themes/user/variflow-tokens';
$config['variflow_contrast_strict'] = false;
Commit the token file to your repository: it's the source of truth from now on.
3. Build
php system/ee/eecli.php variflow:build
[default_site] Published build #1 (3ec6222).
CSS: https://example.test/themes/user/variflow-tokens/default_site/tokens.3ec6222.css
A build checks the file, compiles it and publishes it only if there are no errors. Warnings (a contrast pair under 4.5:1, say) are listed but don't stop it. Add-Ons › Variflow Tokens now lists every token, and Schemes shows each scheme on a sample section.
You can also click Rebuild from file on the Builds page. On development hosts, Variflow also rebuilds by itself on the first control panel request after the file changes.
4. A Tokens field
- Fields › New Field, type Tokens. Name it, for example Section look
(short name
section_look). - Mode: Scheme picker. Editors choose a whole look for a section: every colour in it follows. Leave all schemes ticked, and set the Default value to Light.
- Save, and add the field to a channel: Channels › edit › Fields, or on a fresh site create one (Channels › New Channel, for example Pages, and tick the field on its Fields tab).
Add a second field for a single token if you like: Mode Token picker, Type Color, Groups
color.surface. Name it Section background (section_background). The preview under the
filters shows exactly what editors will be offered.
Open an entry in that channel. The field shows a card for each scheme, drawn in its own colours.
Pick Dark and save. The entry stores scheme:dark, a reference to the scheme rather than its
colours.
5. Use it in a template
Add the stylesheet to your layout's <head>:
{exp:variflow:css}
Then output the field where the section starts:
{exp:channel:entries channel="pages"}
<section {section_look}>
<h2>{title}</h2>
{!-- the entry's other fields --}
</section>
{/exp:channel:entries}
{section_look} outputs data-vf-scheme="dark". Inside that element every token resolves to its
Dark value, so your CSS uses tokens the usual way:
section {
background: var(--vf-color-surface-default);
color: var(--vf-color-text-default);
}
A token field outputs the token's variable, ready for a style attribute or your CSS:
<section style="background: {section_background}">
6. Check it in the browser
Load the page. The section should take the Dark scheme's colours. If it doesn't:
- Is the stylesheet loading? View the page source: there should be a
<link rel="stylesheet" href="…/tokens.<hash>.css">that opens in the browser. - Is the attribute there? The
<section>should havedata-vf-scheme="dark". - Then check the set-up: run
variflow:doctor. It checks the output folder, the CSS URL and the live build.
Next
- Change a colour in the token file, build again, and reload: every entry follows. The Builds page shows what changed.
- Token files: labels editors see, tiers, schemes, derived colours, contrast pairs.
- Deploying: build in your deploy script and keep the live CSS safe.
- Changing tokens: renaming a token that content already uses.
Upgrading
-
Replace both folders,
system/user/addons/variflowandthemes/user/variflow, with the new ones. Don't keep old files behind. -
Add-Ons shows an Update button for Variflow Tokens. Click it, or run:
php system/ee/eecli.php addons:update -a variflow
Until the update runs, the Tokens pages show a banner asking for it.
Your token file, built CSS (in themes/user/variflow-tokens) and stored values aren't touched by
an upgrade. The changelog lists what's new.