Docs /Variflow Tokens

The Tokens fieldtype

A Tokens field lets an editor pick a scheme (a whole section's look), a single token (a background colour, a spacing step, …) or a component's variant (a button's Outline look). The entry stores only a reference, such as scheme:dark, color.surface.inverse or button:outline, never a value. Templates output CSS that points at the live build, so the next build restyles every entry without anyone re-saving it.

Setting up a field

Create a field of type Tokens in Fields: on its own, as a Grid column, or for use inside a Fluid field.

Setting What it does
Mode Scheme picker (recommended): Light, Dark, …, and every colour in the section follows. Token picker: one token. Variant picker (1.3.0): one of a component's variants, such as Primary, Outline or Ghost (below).
Component Variant mode: the component group whose variants editors choose between.
Allowed schemes Scheme mode: which schemes editors may pick. All ticked means "all", including schemes added later.
Filters Token mode: tier, type and groups, combined (a token must match all three). + Spacing and + Radius fill in the space and radius groups. An explicit list (one token per line) overrides the other filters. The preview shows exactly what editors will be offered. A rename with rewrite, a swap or a remap updates the explicit list and default for you (Changing tokens); filters are never changed.
Default value Used when the field is left empty, and when a saved value is no longer in the live build.
Display style Swatches, cards or a dropdown. Grid and Fluid always use the compact picker.
Deprecated choices On (recommended): deprecated tokens aren't offered for new choices. Entries that already use one keep rendering it, and editors are nudged to the replacement.
Template output A reminder of the tags this field outputs.

The choices come from the live build. Until there's one, the field shows a notice and keeps any value it already has.

Good starting points:

  • A section's look: scheme mode, all schemes, default Light.
  • A section background: token mode, type Color, groups color.surface, tier Semantic.
  • Spacing: token mode, + Spacing, display Swatches.
  • A button's style: variant mode, component Button, default Primary.

Variant mode

When the token file gives a component variants, a Variant field lets editors choose the component's look by name: Primary, Outline or Ghost for a button, Raised or Flat for a card. Pick the Component in the field's settings, and a Default (usually the group's default variant).

  • Editors see a card per variant: the component drawn in that variant's colours on the page surface, with its label and description. Grid and Fluid use the compact row; the dropdown display works too. Swatches don't apply.
  • It stores the variant's reference, button:outline, and the tag outputs that value for the data-vf-variant attribute (Component variants). :label outputs the label, :handle the name.
  • Validation: a new value must be a variant of the field's component in the live build.
  • The build guard covers variants as it does tokens: a token file that removes a variant entries still use is refused, and the failed build's Remap offers the component's other variants. Renaming a variant is the same as removing it: remap, or keep the old name until entries move.
  • Works on its own, as a Grid column, inside Fluid and as a Bloqs atom, like the other modes.

What editors see

Editors pick from previews of the live values, never token names:

  • Schemes: cards drawn in each scheme's own colours.
  • Variants: cards with the component drawn in each variant's colours.
  • Colours: swatches; translucent ones sit on a checkerboard.
  • Long colour lists (13 or more, 1.3.0): the swatches are grouped the way the token file is. With choices from color, editors see Action, Surface, Text, … (the group's label when the file gives one), each a heading that opens and closes. Colour ramps (color.bark.50 … color.bark.950) gather in a Palette group, one compact strip per hue in step order; Palette starts closed, unless the value is in it. The current value and the default are pinned on top ("Current: Primary"), so a choice in a closed group is never out of sight. From 25 choices there's a Filter box: it matches labels and token names, and opens the groups that match. The swatches are still one radio group: arrow keys move across every swatch that's showing, whatever its group.
  • Sizes: spacing steps drawn at their size, and radii as corners.
  • Typography: "Aa" in the token's font.

Grid and Fluid use a compact row of small swatches, or a segmented row for sizes.

Tokens the file marks hidden are never offered. An entry that already uses one keeps it: the picker shows it as the current value, and it saves unchanged.

State Shown as
Default (nothing chosen) A dashed ring on the default, and "Using the default: Light."
Selected A solid ring, a check on scheme cards, and a bold label
A retiring choice in use A dashed amber ring and "!", "'Forest' is being retired…", and Switch to … when the replacement is available
The saved choice was removed The default with a dashed red ring and "?", "The saved look was removed. Showing Light until you pick one.", and Choose a look
Read-only Dimmed and locked: "Locked. Ask your site admin to change this."

Use the default (…) goes back to the default (or Clear, when there's none). The pickers follow the control panel's light and dark themes and work from the keyboard: arrow keys move, and Space or Enter picks. Without JavaScript they fall back to plain radio buttons or a dropdown.

Saving

  • A new value must be one of the field's current choices (so never a hidden token).
  • A value that hasn't changed always saves, even if its token has since been deprecated or removed, so editors can always save the rest of the entry.

Grid and Fluid

Tokens fields work as Grid columns, inside Fluid fields, and in Grids inside Fluid. Each cell is tracked separately in the usage index, so renames, conversions and the Usage list on a token's page all see them.

Bloqs

Tokens works as an atom in Bloqs 5 blocks, with every safety feature that covers channel fields. Bloqs is optional: without it, nothing changes.

Set-up. In Bloqs' block definition editor, add an atom of type Tokens. Its settings are the same as a Grid column's: scheme or token picker, allowed schemes, types, groups and a default.

Publishing. Editors get the compact picker in each block, including new, cloned, reordered and nested blocks.

Templates. Atoms take the same tags and modifiers as a field, inside the block's tag pair:

{page_sections}
  {hero}
    <section {look}>
      <h2 style="color: {accent}">{heading}</h2>
    </section>
    {bloqs:children}
  {/hero}
{/page_sections}

What Variflow tracks.

  • Usage: each Tokens atom is recorded in the usage index when the entry saves, and the token's page lists it as "Field › Block › Atom, block N".
  • Drafts: a token used only in a draft block is still in use. A build won't remove it, and the token's page labels those uses Draft.
  • Deleted blocks and definitions: their uses drop out of the index the next time usage is read.
  • Renames, deprecations and remaps rewrite Bloqs atoms too. Undo for those works differently from channel fields: see Changing tokens.

Not covered.

  • Field conversion doesn't convert Bloqs atoms. To move a Color Picker atom to Tokens, add a Tokens atom to the block and re-pick the values.
  • Bloqs 4 and earlier aren't supported. Doctor warns when it finds one.

The usage index

Every saved reference is recorded, per entry, field, Grid cell, Fluid instance and Bloqs atom. That's how:

  • a build knows not to remove a token content still uses;
  • the Tokens page counts uses;
  • a token's page lists exactly where it's used.

The index is updated when entries are saved or deleted. To rebuild it from the stored data, for example after importing entries straight into the database:

php system/ee/eecli.php variflow:usage:rebuild [--site=all] [--dry-run]

About {if field}

An empty Tokens field stores a single space, which means "use the field's default". ExpressionEngine doesn't call a fieldtype for an empty value at all, so this is how the default gets output. As a result {if section_look} is always true. Test the output instead:

{if "{section_look:handle}" == "dark"} … {/if}

Related