Docs /Variflow Tokens

The control panel

Add-Ons › Variflow Tokens has these pages: Tokens, Schemes, Builds, Import, Field conversion, Settings and Docs. They show the current site's live build and how content uses it. They never change token definitions: the token file in your repository is the only place tokens are defined. Where a page changes a token (Rename, Deprecate), it hands you a patch to commit.

Who can do what

Action Who
See the pages Any role with access to the add-on (Roles › CP access › Add-ons)
Rebuild from file, roll back Super admins
Remap removed tokens; cancel or retry queued changes Super admins
Rename, deprecate Super admins, on a licensed site or during the trial
Save settings Super admins, on a licensed site or during the trial
Import: read CSS and review Super admins
Import: download or copy the token file Super admins, on a licensed site or during the trial
Field conversion: pick, review, dry run, finish, undo Super admins
Field conversion: convert Super admins, on a licensed site or during the trial

Every action checks permission on the server, not only by hiding buttons. "During the trial": the 14 days an unlicensed production site gets (Licensing).

Tokens

Every token in the live build, 50 to a page:

  • Filters: tabs by tier (primitive, semantic, component), and filters for type, status (active, deprecated, pending) and group.
  • Search: over names, labels and values.
  • Bookmarkable: the filters are part of the URL, so a filtered list can be bookmarked or shared.
Column Shows
Preview A colour square, a length bar, a radius corner, "Aa" in the typeface, a shadow tile, or the value
Label / token The label editors see, the token name and its tier
Value The value on :root; "Varies in N schemes" links to Schemes
Alias of The token this one points at
Entry refs How many places in content use it directly; the line under it counts indirect use
Status Active, Deprecated (with its replacement), or a pending rename or deprecation

A strip above the list shows the live build, its file hash and counts, and links to Builds. A red strip appears when the newest build failed.

Component variants: when the list includes a group with variants (filter by the component group, say), a strip names each group's variants, with how many times content picks each. Click one to see that group's tokens with the variant's values: "Outline value" marks a token the variant overrides, "follows Outline" one that changes with it (a derived hover). The default variant shows the tokens as they are.

A token's page

Click a token's label:

  • Alias chain: what it resolves through, and what aliases it.
  • Per scheme: its value in each scheme on that scheme's surface, with the contrast results of every pair it's in. A pair a component's variants change shows each variant's result ("with button:outline").
  • Usage: every entry, field, Grid cell and Fluid field that stores it, filterable, with Export CSV.
  • Value: HEX, RGB, OKLCH, the CSS var() and the template tag, each with Copy.
  • Source: the file and line that define it.
  • Rename… / Deprecate…: see Changing tokens.

Schemes

One card per scheme, each showing the same sample section in that scheme's colours. Each card shows:

  • how many sections use the scheme;
  • whether it's the default;
  • its contrast result;
  • the tokens it overrides.

Compare overrides puts every overridden token against every scheme in one table.

Assets

Logos, marks and other images, added and changed without editing the token file. Each card shows:

  • a preview, the file and its alt text;
  • where it comes from: Token file, Added here, or Replaced here (a token file's asset with another file put in its place on this page);
  • each scheme's own file, if any;
  • the templates that name it;
  • Copy tag and Copy CSS.

Add asset opens a form with ExpressionEngine's own file field, so you can drop a file in, upload one, or choose one from the File Manager. You can also type a path (a theme folder) or an https:// address.

  • Name: leave it empty and it's named after the file (hero-bison.jpg is hero-bison).
  • Alt text: or tick decorative.
  • A different file per scheme: for a reversed logo under Dark, for example.

Save checks the file is on the server, then builds at once, so the change is live when the page comes back. A save that would break the build is put back and the reason shown.

  • Edit: changes an asset added here. Its name can change too; templates that use the old name then output nothing.
  • Replace: gives a token file's asset another file. Its name stays.
  • Undo replacement: goes back to the token file's file.
  • Remove: deletes an asset added here, after warning you which templates name it. A token file's asset can only be removed in the file.

What this page saves goes in the assets file, beside the token file: site.tokens.json gets site.assets.json. The token file itself is never written. Commit the assets file with the token file; see The assets file. Changing assets needs a super admin.

Builds

  • Rebuild from file: runs the same build as variflow:build.
  • A failed build: a banner leads with what it means ("Build #48 was not published. Build #47 is still live."), then the cause and the fix. Removed tokens that content still uses are listed with their use counts, and Remap usage… offers a way out. Copy CLI output copies what the command line would print.
  • Diff: the newest build against the one before it: removed, changed (colours and sizes drawn before and after), renamed, deprecated, added, and scheme changes, each with how much content it touches.
  • History: every build, each with its report and diff. A recent build that still has its files offers Roll back to #N.
  • Layout presets: when the token file has a grid, a build's page lists its presets: each one's spans drawn as a bar of columns (and its tablet spans under it), where it stacks, and the narrowest slot it fits in. Defaults marks presets Variflow supplied because the file lists none.
  • Component variants: a build's page lists each component's variants, the data-vf-variant value that applies each, how many tokens it overrides, and whether its contrast pairs pass.
  • Queued changes: renames and deprecations waiting for the token file or a build, with Cancel and Retry.

Import and Field conversion

  • Import turns a stylesheet's custom properties into a draft token file, in three steps: pick CSS, review, download.
  • Field conversion moves an existing Text Input, Select, Radio or Color Picker field onto tokens, in three steps: pick, review, convert.

Both are in Retrofitting a site.

Settings

  • Read-only: the token file, base file, prefix, output folder and output URL. They come from config.php only, because they differ between local, staging and production while the database travels between them. Each has a Copy button for its config line.
  • Editable per site:
Setting Config key Default
Automatic builds variflow_auto_build On for development hosts, off elsewhere
Contrast checks variflow_contrast_strict Warnings
Builds to keep variflow_keep_builds 5

A value set in config.php always wins, and shows as "Set in config.php".

  • Framework maps: each configured map with its coverage ("33 of 45 rules applied") and the rules it skipped.
  • System: versions, licence, the picker assets and the site.

Docs

This guide, inside the control panel.

Multi Site Manager

Every page shows the current site only: its token file, builds, usage and settings. Switch sites with EE's site switcher.

Related