Docs /Variflow Tokens

Retrofitting a site

You don't need to start from scratch. There are three tools for sites that already have CSS and content:

  • Import turns your stylesheet's custom properties into a token file. If your design system is in Figma, Tokens Studio or Sketch, import that instead: see From Figma, Tokens Studio or Sketch.
  • Field conversion moves fields where editors typed colours by hand onto tokens.
  • Framework maps point Bootstrap's own variables at your tokens.

Import from existing CSS

Add-Ons › Variflow Tokens › Import (super admins). It's also linked from Settings and from the empty Tokens page.

  1. Pick CSS: paste a stylesheet, or give the path to a .css file inside the site folder (up to 1 MB).
  2. Review:
    • What gets imported: custom properties on :root, html or :host become tokens. Properties under a dark-mode selector ([data-theme="dark"], [data-bs-theme=dark], .dark, @media (prefers-color-scheme: dark)) become scheme overrides, and var(--other) becomes a reference.
    • Prefixes: a prefix most names share (--bs-) is dropped.
    • Per row: rename the token, change its type or tier, or leave it out.
    • Confidence: a value's form (#0d6efd, 16px) gives high confidence. A guess (a named colour, a unitless number) gets medium confidence, marked check.
    • Not imported: anything that can't be classified (calc(), color-mix(), a property only set inside .card) is listed with the reason, and isn't imported unless you pick a type for it.
  3. Token file:
    • the draft, with Download and Copy JSON;
    • the variflow:import command that writes the same file;
    • if the site has no token file yet, the config line to add.

Import never writes your token file. Review the draft, add labels and contrast pairs, commit it, then build. From the command line:

php system/ee/eecli.php variflow:import themes/user/site/css/main.css

This writes site.tokens.import.json next to your token file; --json prints it instead. Reviewing works without a licence; downloading or writing the draft needs one after the 14-day trial (Licensing).

Convert a field to Tokens

For fields where editors typed hex codes, or picked from a hand-made Select: Text Input, Select Dropdown, Radio Buttons and Color Picker fields, and Grid columns of those types.

  1. Pick field:

    • The list shows each field and Grid column you can convert, where it's used, and how many entries have a value.
    • Choose one, and you get the Tokens settings form, pre-filled from what the field holds. Every value names a scheme? Scheme mode. Mostly colours? Token mode, with the colour tokens the values match.
  2. Review mappings. One row per distinct stored value: how many entries hold it, the nearest token, the confidence, and Map to.

    • Exact: the same colour (or the token's name, label or value), within ΔE 0.5.
    • High: within ΔE 2.
    • Medium: within ΔE 5. It's pre-filled but outlined amber: check it.
    • Outliers (Low, No value, Unparseable) never map on their own. They become the field default unless you pick a token for them. Keep outliers as raw values is an escape hatch: editors then see those values as unresolved.

    ΔE is how different two colours look: about 1 is the smallest difference anyone notices side by side.

    Dry run says how many values and entries would change, and how many revisions would be saved. It writes nothing.

  3. Convert:

    • Backup first: the field's current values are saved.
    • The switch: the field becomes a Tokens field with the same short name, and every value is rewritten.
    • Revisions: each changed entry gets a revision where versioning is on.
    • The result has Undo conversion, which puts the old type, settings and values back. A value an editor changed since the conversion is left alone.

Templates keep working. {hero_bg} now outputs var(--vf-…), which works anywhere the old hex worked in CSS. Use {hero_bg:value} where you need the literal value.

Things to know:

  • A field's uses inside Fluid are converted with it.
  • Changes during the review: if an entry's value changes after you review, Convert refuses and asks you to review again.
  • Interrupted runs: they show Finish conversion, which carries on where it stopped.
  • Large fields: the control panel converts up to 20,000 values at a time. For more, it gives you the command to run.
  • Licence: reviewing and dry runs are free; Convert needs a licence after the 14-day trial.

From the command line:

php system/ee/eecli.php variflow:convert hero_bg --dry-run
php system/ee/eecli.php variflow:convert hero_bg --accept-medium
php system/ee/eecli.php variflow:convert:undo 12

See Command line for every option.

Framework maps: Bootstrap 5.3

A framework map sets a CSS framework's own variables from your tokens. With the Bootstrap 5.3 map, --bs-body-bg, --bs-primary, the button variables and the rest follow your tokens in every scheme. You don't edit Bootstrap's CSS.

$config['variflow_maps'] = ['bootstrap-5.3'];

Then build. The build prints the coverage ("33 of 45 rules applied"), and Settings › Framework maps lists the rules it skipped and the token each one needs.

  • Load order: put {exp:variflow:css} after Bootstrap's stylesheet.

  • Which tokens it reads: the usual role names, as in the starter and demo files: color.surface.default, color.text.default, color.text.link, color.border.default, color.action.primary, color.feedback.danger, radius.control, and so on.

  • Missing tokens: a rule whose token you don't have is skipped, and Bootstrap's own value stays. The map never fails a build.

  • Dark mode: set Bootstrap's and Variflow's attributes together on a section:

    <section data-vf-scheme="dark" data-bs-theme="dark">…</section>
    

Maps never change token values, and they're never licence-gated.

Related