Variflow Tokens Changelog
Changelog
1.3.0 (unreleased)
- Assets: logos and other files in the token file.
$extensions.variflow.assetsnames files that aren't tokens, each a path from the site root or anhttps://URL, with a label and alt text. A scheme swaps a file in its ownassets(a reversed logo under Dark). Each asset compiles to--vf-asset-<name>: url(…), which followsdata-vf-schemelike a token.{exp:variflow:asset}outputs the URL, an<img>, or the SVG inline withrole="img"and its alt text, refusing a file with script or outside links. Verify and build report an invalid name or value, a scheme swapping an undeclared asset, and a file missing under the site root, each with its line. The manifest gains anassetsmap. A token file without assets builds byte for byte as before. See Assets. - Control panel: an Assets page. Tokens › Assets lists every asset with a preview, its alt
text, each scheme's file, the templates that name it, and Copy tag / Copy CSS. Add asset uses
ExpressionEngine's own file field (drop, upload, or choose from the File Manager), names the asset
after the file, and builds on save, so the change is live at once. A token file's asset can be
replaced and the replacement undone. The page never writes the token file: it saves to an
assets file beside it (
site.assets.jsonforsite.tokens.json), which builds lay over the token file and which counts toward the build's file hash. With no assets file, hashes are as before. See Assets. - Integration API 5:
namedAssets()andnamedAsset()list and resolve the site's assets for other add-ons (Builder's image fields offer them). See Assets. - A build whose CSS matches an older build's no longer fails writing that build's source copy when the files it came from differ (a reformatted token file, say).
- Import: Sketch exports, and line heights in pixels. Design-token Import now turns
typography line heights written in pixels (
40,40px, as Sketch, Tokens Studio and Figma write them) into the ratio CSS expects (1.25on a 32px font), and150%into1.5. Before,40compiled toline-height: 40. Sketch's0for an Auto line height is left out rather than compiled toline-height: 0. Typography fields with no place in a token (color,textTransform) and objects with fields but no$valueare now listed in the review instead of disappearing. See From Sketch. - Licensing: a 14-day trial. A production site without a valid licence now works fully for
14 days from the first time Variflow sees the problem (a new site, or a renewal that lapsed),
with a banner counting down for members who can act on it (dismissable for the browser
session). After that, saving Settings, rename and deprecate, Import's download, save and use,
Field conversion's Convert, and writing from
variflow:import,variflow:import:tokensandvariflow:convertstop until a licence is added. Before, they stopped at once. Front-end output, template tags, fields and pickers, builds (including a deploy's), remap and every control panel page never stop. See Licensing. - Only EE's statuses that name Variflow (
invalid,expired) count as unlicensed. EE's own messages about the ExpressionEngine installation's licence (such asupdate_availableorlicense_expired) no longer count against Variflow; before, any status butvalid,trialornadid. $config['bison_dev_domains']marks development hosts for every Bison Digital add-on, asvariflow_dev_domainsdoes for Variflow;$config['variflow_simulate_license'] = 'grace'or'lapsed'shows a dev site what an unlicensed one gets.variflow:doctorand Settings show the trial's days left.- The guide is online at gobison.digital/documentation/variflow.
- Grouped colour picker. A long list of colours (13 or more) is grouped the way the token
file is: Action, Surface, Text, … with the file's label for a group when it has one, each a
heading that opens and closes. Numbered ramps (
color.bark.50….950) gather in a Palette, closed until opened, one compact strip per hue in step order. The current value and the default are pinned on top, and from 25 choices a filter box matches labels and token names. Still one radio group from the keyboard. Tokens fields and Variflow Builder's inspector both get it. See What editors see. - Pickers list a group's tokens in the token file's order (they were sorted by name, so
bark.50came afterbark.400). An explicit list keeps its own order. - Hidden tokens.
"$extensions": { "variflow": { "hidden": true } }on a token or a group keeps it out of every picker; it still compiles, resolves and can be referenced, and content that already uses one still shows it and saves. The build refuses ahiddenthat isn't true or false, on its line. See Hiding tokens from editors. - Integration API 4:
tokens()says which tokens arehidden; picker payloads carry the saved value even when it's hidden (hidden: true) and the file's group headings (groups). - The Fernhaven demo hides its illustration colours, mix target, caption scrim and shadow colours from editors.
- The Fernhaven demo's journal has six stories (four new, across its three topics, with their own
dates), enough to try Builder's entry picker and the latest-entries grid. On a demo that's
already seeded,
variflow:dev:fernhaven --refreshadds the stories it lacks (by URL title) and never edits or deletes existing ones; with Structure on, they're listed under Journal. - Picker labels wrap between words (Variflow Builder B6a): a swatch, step, card or dropdown
label in a narrow column breaks only between words, never inside one ("Seconda ry"); a single
word that can't fit is cut with "…" and the label's tooltip has it all. Pickers no longer
inherit a host page's
overflow-wrap: anywhere. - Use as the token file. On a site with no token file, Import › Design tokens offers Use as
the token file once the draft is saved: it renames
site.tokens.import.jsontosite.tokens.jsonand links to Rebuild. It never replaces a token file. On the command line:variflow:import:tokens --use-as-token-file. See Importing design tokens. - The build manifest records each token's
hiddenand fileposition, and the labels and descriptions of groups that have them. - Template generator: EE's
generate:templateswrites a useful example for each Tokens field (a scheme attribute, a variant attribute or a token value), in channel fields, Grid, Fluid and Bloqs. - Grid tokens and layout presets. Define the site's grid in the token file (
grid.columns,grid.gutter,grid.container.defaultand.wide,grid.minSpan,breakpoint.sm/md/lg) and the layout presets pages are built from (full,8/4,3-across, …) in$extensions.variflow.presets, each with its spans, where it stacks and optional tablet spans. The build checks them and reports a problem on its line; with no presets you get sensible defaults. See Grid and layout presets. - The layout stylesheet, opt-in:
{exp:variflow:layout_css}renders any preset fromdata-vf-layout,data-vf-containeranddata-vf-orderattributes, with its reflow. Layouts nest and reflow by their own width (container queries). No framework, no utility classes. See Layouts. Widths that aren't a preset (what Variflow Builder's column dividers make) aredata-vf-layout="custom", each item's span in its--vf-span: one rule. - The build page lists the presets with a diagram of each;
variflow:doctorsays when they're the defaults. - Integration API 2:
ee('variflow:Integration')->grid($siteId)gives other add-ons the grid and presets, each with its fit width (minSlot), so a page builder offers only presets that fit.Integration::API_VERSIONis 2; nothing from 1 changes. - The Fernhaven demo has a grid: its product cards are a
4-acrosslayout and its story teasers a6/6with the image first on phones. - A token file without a grid builds exactly as before.
- Component variants. A group under
componentcan declare named variants ($extensions.variflow.variantsanddefaultVariant): Primary, Outline and Ghost for a button, each a set of overrides on the group's own tokens.data-vf-variant="button:outline"applies one to an element and everything in it; several components can share the attribute. Every variant resolves correctly under every scheme, in any nesting order, and derived colours in the group (a hover) follow the variant. The build checks names, the default, each override's group, type and references, and schemes that would fight a variant, each on its line. See Component variants. - Contrast for pairs with a component token is checked in every scheme × variant combination; a failure names the combination.
- Variant mode for Tokens fields: editors pick a component's variant from cards drawn in its
colours; the tag outputs the attribute value (
button:outline). Works in Grid, Fluid and Bloqs. See Variant mode. - Variant references are content: usage counts them, the build guard refuses removing a variant entries use, and the Remap screen offers the component's other variants. Renaming a token rewrites variant overrides that refer to it.
- The token browser shows a group's variants, with how often each is picked, and a toggle to see
its tokens per variant; the build page and
variflow:buildlist the variants; contrast results show the scheme and variant. - Integration API 3:
variants($siteId, $group)lists each group's variants with labels, the default and a preview of the tokens each changes;output()andhas()take variant references; pickers have avariantmode; content sources may store variant references.Integration::API_VERSIONis 3; nothing from 1 or 2 changes. - The Fernhaven demo has button (Primary, Outline, Ghost) and card (Raised, Flat) variants, used across its templates, and its call-to-action block's card button is a Variant field.
- A token file without variants compiles byte for byte as before.
- Fix: usage for content sources (Bloqs, other add-ons') is current after the first save of an
existing entry. EE runs
after_channel_entry_savebefore it writes an updated entry's field data, so a source that reads field data recorded the previous values until the next save; the sync now runs again once the data is written. - The design-token import takes an extras file: a small JSON file beside the export for what
Figma and Tokens Studio can't carry: layout presets, component variants, scheme labels and
descriptions, group and token descriptions, flags such as
hidden, and your own contrast pairs. Choose it as Extras file in Import › Design tokens, or pass--extras=<file>tovariflow:import:tokens. It's merged in before the review, which lists what it added; an entry naming a scheme, group or token the import doesn't have is left out, with a warning on its line. Its contrast pairs replace inferred ones. See The extras file. - Contrast-pair inference no longer pairs a border with the background it outlines: one in its own
group (
component.card.borderandcomponent.card.background, and the background's hover and pressed shades), or one it takes its colour from (a filled button whose border is its fill). The review lists what it left out. Focus rings are paired as before. - Fix: Import › Design tokens › Save draft failed when the token file's folder
(
system/user/config/tokens/by default) didn't exist yet. It now creates the folder, asvariflow:import:tokensdoes (0775, with its parents), and says so plainly when it can't. - Fix: on ExpressionEngine 7.3.0 with PHP 8.2+,
variflow:build,variflow:rollbackandvariflow:usage:rebuildprinted "E_DEPRECATED: Creation of dynamic property …$_trans_failure" (from EE 7.3.0's own database driver, on every transaction). Variflow no longer sets it off.
1.2.0 (unreleased)
- Integration API for add-on developers. Other add-ons (page builders, block editors) can
offer Variflow's own picker in their editors, output values exactly as a Tokens field tag does,
and check their configuration against the live build, through
ee('variflow:Integration'). See the new Developers page. - Content sources. An add-on that stores token references in its own tables registers a
content source through the
variflow_content_sourcesextension hook. Its content is then covered by usage tracking, the build guard, renames with rewrite, remaps and Undo, like a Tokens field. - The hook, the
ContentSourceinterface and the Integration service are public and follow semver from 1.2.0 (Integration::API_VERSIONis 1). - The token page's Usage list shows other add-ons' content with their own description, linking to where it's edited.
- A rewrite or remap that another add-on's source declines to write counts it as skipped, and the change's note says so.
variflow:doctorlists the content sources with their usage counts, any that were skipped (an invalid or taken name, or one that throws), and usage left by sources no add-on registers any more.
1.1.0 (unreleased)
- Bloqs 5 support. Tokens works as a Bloqs atom: settings, the picker in new, cloned, reordered and nested blocks, and every template tag and modifier.
- Every safety feature covers Bloqs: the usage index, the build guard (draft blocks count),
renames and deprecations with rewrites, remaps and
variflow:usage:rebuild. - Undo on the Builds page puts back Bloqs atoms and picker settings a change rewrote, since entry revisions don't hold them.
- The token page's Usage list names Bloqs locations ("› Hero › Accent, block 2") and labels drafts.
variflow:doctorreports Bloqs and warns on an unsupported version.- Rewrites save an entry revision only when the entry's channel fields changed.
- The demo token set is now Fernhaven Outfitters (
variflow:init --demo): five schemes (Light, Dark, Brand, Muted, Seasonal), hover and pressed shades that mix toward a per-scheme token, and 23 contrast pairs that pass in every scheme. It replaces the Kestrel set. - Import a Figma or Tokens Studio design system, with modes as schemes. Give
variflow:import:tokens(or Import › Design tokens) Figma's per-mode variable export, a Tokens Studio file or folder, or a DTCG 2025.10 resolver document. Pick the default mode, and you get a draft token file in which every other mode is a scheme holding only what differs, references kept. With several mode groups you pick the one that becomes schemes. Unsupported tokens are listed, never dropped silently, and the import never writes the live token file. - The design-token import infers what an export has no place for: editor labels, tiers,
contrast pairs, and hover and pressed shades as derive rules (
color-mix()toward black, white, transparent or a per-schemecolor.mix.target). Each comes from a naming convention, with its reason; failing pairs are kept and flagged, and what no convention reveals is listed instead of guessed. Turn a kind off (--no-labels,--no-tiers,--no-pairs,--no-derive) or untick single items in the control panel. Every token still resolves to its imported value. variflow:verify --file=<path>checks a draft against the site's content before you swap it in.- Tokens Studio font family lists (
"Inter, sans-serif") are read as lists of families.
Fixed
- Renames with rewrite, deprecate-and-swap and remaps now update the pickers' own settings too: a Tokens field's, Grid column's or Bloqs atom's explicit list and default that named the old token name the new one (Undo puts them back). Filter-only pickers that would stop offering the token are reported, not changed.
- A stored reference that neither the live build nor the new file has as a token (already broken, or only a rename alias) can now be remapped: the Remap screen offers every token in both builds, nearest names first, and says the type is unknown.
1.0.0 (unreleased)
The first release.
- Builds:
- validates a W3C DTCG token file (references, loops, CSS name collisions, contrast pairs
in every scheme) and compiles it to one hashed stylesheet, with cascade layers, scheme
blocks and
color-mix()derived colours; - publishes only when there are no errors;
- keeps the last five builds for rollback;
- auto-build on development hosts.
- validates a W3C DTCG token file (references, loops, CSS name collisions, contrast pairs
in every scheme) and compiles it to one hashed stylesheet, with cascade layers, scheme
blocks and
- Command line:
variflow:init(--demowrites the Kestrel demo set),variflow:verify,variflow:build,variflow:rollback,variflow:usage:rebuild,variflow:rewrite:run,variflow:import,variflow:convert,variflow:convert:undoandvariflow:doctor. - The Tokens fieldtype:
- scheme cards, colour swatches, spacing steps, radii and a dropdown, with the compact picker in Grid and Fluid;
- every editor state (default, retiring, removed, read-only) shown the same way;
- works without JavaScript.
- Templates:
{exp:variflow:css},{exp:variflow:value}, and field tags with:value,:name,:label,:classand:handle. - The usage index: every stored reference, per entry, field, Grid cell and Fluid instance. A build that would remove a token in use stops and says where it's used.
- The control panel: Tokens, token detail, Schemes, Builds (with diffs, history and rollback), Import, Field conversion, Settings and the built-in guide.
- Changing tokens: rename and deprecate with a patch to commit, an optional queued rewrite of stored data, and remap of removed tokens.
- Retrofitting:
- import a stylesheet's custom properties as a draft token file;
- convert Text Input, Select, Radio and Color Picker fields to Tokens fields, with a review of every value, a dry run, resumable runs and Undo.
- Framework maps: a Bootstrap 5.3 preset, and your own map files.
- Multi Site Manager: per-site token files, builds, usage and settings, with an optional shared base file.
- Requirements: ExpressionEngine 7.3+ and PHP 8.2+.
Developed in phases 0–7 (versions 0.1–0.9 were pre-releases); see the repository for the history.