Bring your own CSS
Builder renders your partials, so every page is your own markup. It doesn't ship a theme. You style parts with whatever you already use: plain CSS, Tailwind, UnoCSS, daisyUI, Bootstrap, Bulma, Foundation or Open Props. This page is what Builder and Variflow Tokens give you to style with, three rules that keep a framework from fighting the layout, and a short recipe for each.
What's on the page
A Builder page loads three stylesheets:
| Stylesheet | Tag | What it does |
|---|---|---|
| Token stylesheet | {exp:variflow:css} |
Every token as a CSS variable on :root, one block per scheme, one per component variant, and any framework map. |
| Layout stylesheet | {exp:variflow:layout_css} |
Sections' content widths and the layouts' columns. Builder needs it. |
| Yours | your <link> |
Everything else. |
<head>
<style>@layer reset, base, variflow, components, utilities;</style>
<link rel="stylesheet" href="/css/site.css">
{exp:variflow:css}
{exp:variflow:layout_css}
</head>
The <style> line sets the cascade layers' order (rule 3).
It can live at the top of your own stylesheet instead, if that loads first.
The hooks
Attributes
Builder and Tokens style through attributes, not classes, so your class names never clash with theirs.
| Attribute | Where it comes from | |
|---|---|---|
data-vf-layout="8/4" |
Builder, on every layout | A grid of the preset's columns. One plain <div> per column, nothing else. custom for spans set with the column dividers. |
data-vf-order="reverse" |
Builder, on a layout set to Last column first | While the columns are stacked, the last comes first. |
data-vf-container="default" |
Your section partial: data-vf-container="{vfb:container}" |
The content width: default, wide or full. |
data-vf-scheme="dark" |
{vfb:attrs}, from a part's look |
The scheme's token values for everything inside, and its background and text colour on the element itself. The class vf-scheme-dark does the same. |
data-vf-variant="button:outline" |
{vfb:attrs}, from a part's variant |
The variant's component tokens for everything inside. Several are separated by spaces (card:flat button:ghost); match one with [data-vf-variant~="button:outline"]. |
Builder also adds data-vfb-id and keeps your data-vfb-field markers in the editor's preview
only. Visitors never get them, so don't style them.
Custom properties
| Property | |
|---|---|
--vf-<token> |
Every token, by its name with hyphens: color.surface.default is --vf-color-surface-default, space.xl is --vf-space-xl. Names are lowercased (grid.minSpan is --vf-grid-minspan). A typography token has one per part: --vf-typography-body-font-size. $config['variflow_prefix'] changes vf. |
--vf-component-<component>-<property> |
A component's tokens (--vf-component-button-background), which data-vf-variant switches. Style the component once with these. |
--vf-grid-columns, --vf-grid-gutter, --vf-grid-container-default, --vf-grid-container-wide |
The grid. Schemes can change the gutter and widths. |
--vf-span |
On a column of a custom layout: its width in grid columns (style="--vf-span: 7"). Builder writes it; the layout stylesheet reads it. |
Schemes and variants re-declare tokens on their element, so var(--vf-color-surface-default)
anywhere inside a dark section is the dark value. That's what makes a component styled once look
right in every scheme.
Partial variables
Most of what a partial needs to style is in Pages › Variables. These three are for layout:
| Variable | |
|---|---|
{vfb:container} |
A section's content width (default, wide, full). Put it on your wrapper as data-vf-container="{vfb:container}". |
{vfb:span} |
The width of the column the part sits in, in grid columns (12, 8, 4 …), from the presets around it. The same on every screen. |
{vfb:narrow} |
The component's narrowLayout name when its column is narrower than below, otherwise nothing (Parts). Use it to switch markup: three across in a wide column, a list in a narrow one. |
{vfb:attrs} (the scheme and variant attributes) goes on the element they should style, and
{vfb:appearance:<name>} gives a token control's value as var(--vf-…), for an inline style or
a custom property.
What the layout stylesheet does, and what it leaves to you
It does:
- Containers:
data-vf-containeris centred, at most--vf-grid-container-defaultor-widewide, with the gutter as side padding.fullis edge to edge, with no padding. - Layouts:
data-vf-layoutis a CSS grid of--vf-grid-columnscolumns with--vf-grid-gutterbetween them. Its columns take the preset's spans. - Reflow: columns stack below each preset's breakpoint, and take tablet spans where the preset
has them. These are container queries on the layout's own width, so a layout nested in a narrow
column stacks as it would on a phone. Each layout is a size container (
container-type: inline-size). - Phone order (
data-vf-order) and custom spans (--vf-span).
Everything is in the variflow.layout cascade layer, and it sets no colours.
It leaves to you:
- the space above and below sections (Builder gives you
{vfb:appearance:…}for it), and between components stacked in one column; - everything inside a column: components, type, images, buttons;
- colours beyond a scheme's background and text colour.
Don't change gap or column-gap on a layout: that's the gutter. row-gap and align-items are
yours.
Three rules
1. Builder owns the outer grid
Sections, layouts and columns are Builder's. Don't put a framework's grid on them: no
.container, .row, .col-*, .columns, .grid-x or grid-cols-* in a section partial, and
nothing that targets [data-vf-layout] or its columns except row-gap and align-items. Editors
choose layouts from the token file's presets, and the editor, the canvas and the layout stylesheet
all work from those.
Inside a component, use any grid you like: a row of cards, a form, a gallery. But most framework grids switch at screen widths, and a component doesn't know how wide its column is on a screen. Choose the markup from the column instead:
{vfb:narrow}or{vfb:span}in the partial:row-cols-1{if vfb:narrow == 'stack'}{if:else} row-cols-md-3{/if};- or a container query on the component itself (Tailwind's
@container, or your owncontainer-type: inline-size). The nearest container is otherwise the whole layout, not the column.
2. Map the framework's variables to tokens, never the reverse
The token file is the one source for colours, sizes and fonts: editors pick from it, Tokens checks
contrast and tracks usage from it, and schemes and variants switch it. So point the framework's
variables at the tokens (--bs-body-bg: var(--vf-color-surface-default)), and never write a token
from a framework value.
Declare the mapping where schemes can change it. A custom property that holds var(…) is
worked out on the element that declares it, and its children inherit the result. Declared only on
:root, --bs-body-bg is the root's surface colour everywhere, dark sections included. Declare it
on the root and on every scheme:
:root, [data-vf-scheme] {
--bs-body-bg: var(--vf-color-surface-default);
--bs-body-color: var(--vf-color-text-default);
}
Add [data-vf-variant] for variables mapped from component tokens, or set those on the component
itself (as .btn-vf does in the Bootstrap recipe). A utility that uses var(--vf-…) directly
(Tailwind's @theme inline, Tailwind v3's and UnoCSS's theme values) needs none of this.
3. Put Variflow between your base and your components
The token stylesheet declares its layers in this order, and the layout stylesheet adds its own:
@layer variflow.tokens, variflow.schemes, variflow.variants, variflow.maps; /* {exp:variflow:css} */
@layer variflow.layout { … } /* {exp:variflow:layout_css} */
All five are inside one layer, variflow. (variflow.variants is there when the token file has
component variants.) Name it once, in your own order, before any of them load:
@layer reset, base, variflow, components, utilities;
- Reset and base below
variflow. A reset's* { padding: 0 }would otherwise take the containers' gutter padding away, and a basesection { background: … }would beat the scheme's colours. - Components and utilities above it. Your components win over the layout and the schemes without fighting specificity, and so does a utility you put on purpose.
- The first statement wins. The order is set where a layer is first named, so this line goes before Tailwind's, Bootstrap's or Variflow's CSS. Later statements only add new names at the end.
- Unlayered CSS beats every layer. A framework loaded as is (most are unlayered) beats the layout stylesheet and the schemes wherever its selectors match. Put it in a layer, as the recipes below do.
- Framework maps. Tokens' Bootstrap 5.3 map is unlayered, so it beats
Bootstrap's own variables wherever Bootstrap is. Load
{exp:variflow:css}after Bootstrap.
Recipes
Each recipe was built with the tool's own CLI in a scratch folder, with nothing installed in the site, and checked in Chromium against the Fernhaven demo token file: the layouts' columns and the containers' padding come through, and the same markup takes each scheme's and each variant's colours. Versions are the ones tested. Token names are Fernhaven's; use your own.
Install the tool where your CSS is built first, as a dev dependency (npm i -D tailwindcss@4 @tailwindcss/cli@4, npm i -D bootstrap@5.3 sass, and so on). @import "tailwindcss" and the
Sass imports need the package installed, not just npx.
| Recipe | Tested with | Build |
|---|---|---|
| Plain CSS | Lightning CSS 1.0.0-alpha.72 (optional) | npx lightningcss-cli --minify css/site.css -o build/site.css |
| Tailwind v4 | Tailwind CSS 4.3.5 | npx @tailwindcss/cli -i css/site.css -o build/site.css --minify |
| Tailwind v3 | Tailwind CSS 3.4.19 | npx tailwindcss -i css/site.css -o build/site.css --minify |
| UnoCSS | UnoCSS 66.13.0 | npx unocss "_sections/**/*.{html,json}" -c uno.config.mjs -o build/uno.css -m |
| daisyUI | daisyUI 5.8.0, Tailwind CSS 4.3.5 | as Tailwind v4 |
| Bootstrap 5.3 | Bootstrap 5.3.9, Dart Sass 1.108.2 | npx sass --load-path=node_modules scss/site.scss build/site.css |
| Bulma 1.x | Bulma 1.0.4, Lightning CSS | npx lightningcss-cli --bundle --minify css/site.css -o build/site.css |
| Foundation 6 | Foundation 6.9.0, Dart Sass 1.108.2 | npx sass --load-path=node_modules scss/site.scss build/site.css |
| Open Props | Open Props 1.7.23, Lightning CSS | npx lightningcss-cli --bundle --minify css/site.css -o build/site.css |
The paths assume your stylesheet sits beside the site's templates; change ../_sections to where
system/user/templates/<site>/_sections/ is from your CSS.
Plain CSS
No build step. Layer your reset and base below Variflow, style components with tokens.
css/site.css
@layer reset, base, variflow, components, utilities;
@layer reset {
*, *::before, *::after { box-sizing: border-box; }
* { margin: 0; padding: 0; } /* below variflow, so containers keep their padding */
}
@layer base {
body { font-family: var(--vf-font-family-body); line-height: var(--vf-line-height-normal); }
a { color: var(--vf-color-text-link); }
}
@layer components {
.band { padding-block: var(--band-above, 0) var(--band-below, 0); }
[data-vf-layout] > * > * + * { margin-top: var(--vf-space-md); } /* components stacked in a column */
.card {
background: var(--vf-component-card-background);
border: 1px solid var(--vf-component-card-border);
border-radius: var(--vf-radius-lg);
box-shadow: var(--vf-component-card-shadow);
padding: var(--card-padding, var(--vf-space-lg));
}
.card--compact { padding: var(--vf-space-md); }
}
band.section.html and card.component.html
<section class="band" {vfb:attrs} style="--band-above: {vfb:appearance:space_above}; --band-below: {vfb:appearance:space_below};">
<div data-vf-container="{vfb:container}">{vfb:content}</div>
</section>
<article class="card{if vfb:narrow} card--{vfb:narrow}{/if}" {vfb:attrs} style="--card-padding: {vfb:appearance:padding};">
<h3 data-vfb-field="heading">{vfb:field:heading}</h3>
{if vfb:field:text}<p data-vfb-field="text">{vfb:field:text:br}</p>{/if}
</article>
The card's schema has a variant control on component.card, a look that defaults to
inherit, a padding control on the space group, and "narrowLayout": {"below": 6, "name": "compact", "label": "Compact"}.
Tailwind v4
source(none)and@source: scan the_sections/folder (partials and schemas) and your own templates, nothing else.@theme inline: point the theme atvar(--vf-…).inlinewrites the variable into each utility (.bg-button { background-color: var(--vf-component-button-background) }), so it follows schemes and variants. Without it, Tailwind's--color-buttonis worked out once on:rootand every scheme gets the root's colours (rule 2).--color-*: initialdrops Tailwind's palette, so a partial can't reach forbg-red-500.- Layers: Tailwind's own are
theme, base, components, utilities. Namevariflowafterbase(Preflight) before the import.
css/site.css
@layer theme, base, variflow, components, utilities;
@import "tailwindcss" source(none);
@source "../_sections";
@source "../templates";
@source inline("@3xl:grid-cols-{2,3}"); /* built from a field value: see Gotchas */
@theme inline {
--color-*: initial;
--color-surface: var(--vf-color-surface-default);
--color-ink: var(--vf-color-text-default);
--color-muted: var(--vf-color-text-muted);
--color-primary: var(--vf-color-action-primary);
--color-button: var(--vf-component-button-background);
--color-button-hover: var(--vf-component-button-background-hover);
--color-button-text: var(--vf-component-button-text);
--color-button-border: var(--vf-component-button-border);
--font-body: var(--vf-font-family-body);
--text-lg: var(--vf-font-size-lg);
--spacing-sm: var(--vf-space-sm); /* p-sm, gap-sm, beside the numeric scale */
--spacing-md: var(--vf-space-md);
--spacing-lg: var(--vf-space-lg);
--radius-md: var(--vf-radius-md);
--radius-lg: var(--vf-radius-lg);
}
button.component.html and tiles.component.html
<a class="inline-flex items-center gap-sm rounded-md border-2 border-button-border bg-button px-lg py-sm font-semibold text-button-text hover:bg-button-hover" {vfb:attrs} href="{vfb:field:link:url}" data-vfb-field="link">{vfb:field:link:label}</a>
<div class="@container rounded-lg p-lg {vfb:field:align}" {vfb:attrs}>
<div class="{if vfb:narrow == 'list'}flex flex-col gap-sm{if:else}grid grid-cols-1 gap-md @md:grid-cols-2 @3xl:grid-cols-{vfb:field:columns}{/if}">{vfb:content}</div>
</div>
@container makes the component its own container, so @md: and @3xl: follow its column, not
the screen. The align field's option values are whole class names (text-left,
text-center), which Tailwind finds in the schema; columns is 2 or 3, so the class is
safelisted with @source inline().
Tailwind v3
Utilities take theme values as they are, so var(--vf-…) follows schemes with no extra step.
Tailwind v3 doesn't output native cascade layers; wrap its three directives in your own.
tailwind.config.js
module.exports = {
content: ['./_sections/**/*.{html,json}', './templates/**/*.html'],
safelist: [{ pattern: /^grid-cols-(2|3)$/, variants: ['@3xl'] }],
theme: {
colors: { // replaces the palette: tokens only
surface: 'var(--vf-color-surface-default)',
ink: 'var(--vf-color-text-default)',
muted: 'var(--vf-color-text-muted)',
button: {
DEFAULT: 'var(--vf-component-button-background)',
hover: 'var(--vf-component-button-background-hover)',
text: 'var(--vf-component-button-text)',
border: 'var(--vf-component-button-border)',
},
},
extend: {
spacing: { sm: 'var(--vf-space-sm)', md: 'var(--vf-space-md)', lg: 'var(--vf-space-lg)' },
borderRadius: { md: 'var(--vf-radius-md)', lg: 'var(--vf-radius-lg)' },
fontFamily: { body: 'var(--vf-font-family-body)' },
},
},
plugins: [require('@tailwindcss/container-queries')],
};
css/site.css
@layer tw-base, variflow, tw-components, tw-utilities;
@layer tw-base { @tailwind base; }
@layer tw-components { @tailwind components; }
@layer tw-utilities { @tailwind utilities; }
The layer names mustn't be base, components or utilities: Tailwind v3 treats those as its
own directive. Opacity modifiers (bg-button/50) don't work on var() colours in v3.
UnoCSS
Use presetWind3: it writes theme values into each utility, so var(--vf-…) follows schemes.
(presetWind4 puts the theme in variables on :root, which have the problem in
rule 2.)
uno.config.mjs
import { defineConfig, presetWind3 } from 'unocss';
export default defineConfig({
presets: [presetWind3()],
outputToCssLayers: true, // layers named preflights, shortcuts, default
safelist: ['@3xl:grid-cols-2', '@3xl:grid-cols-3'],
theme: {
colors: {
surface: 'var(--vf-color-surface-default)',
muted: 'var(--vf-color-text-muted)',
button: {
DEFAULT: 'var(--vf-component-button-background)',
hover: 'var(--vf-component-button-background-hover)',
text: 'var(--vf-component-button-text)',
border: 'var(--vf-component-button-border)',
},
},
spacing: { sm: 'var(--vf-space-sm)', md: 'var(--vf-space-md)', lg: 'var(--vf-space-lg)' },
borderRadius: { md: 'var(--vf-radius-md)', lg: 'var(--vf-radius-lg)' },
fontFamily: { body: 'var(--vf-font-family-body)' },
},
});
The CLI takes the files to scan as arguments:
npx unocss "_sections/**/*.{html,json}" "templates/**/*.html" -c uno.config.mjs -o build/uno.css -m
UnoCSS's own layer statement doesn't name variflow, so set the order in the page's <head>,
before its CSS:
<style>@layer preflights, variflow, shortcuts, default;</style>
daisyUI
daisyUI 5 is a Tailwind v4 plugin. Turn its themes off and set its theme variables from tokens on
the root and every scheme, so each data-vf-scheme is a daisyUI theme of its own. Builder's
schemes replace data-theme.
css/site.css
@layer theme, base, variflow, components, utilities;
@import "tailwindcss" source(none);
@source "../_sections";
@plugin "daisyui" { themes: false; }
:root, [data-vf-scheme] {
color-scheme: light;
--color-base-100: var(--vf-color-surface-default);
--color-base-200: var(--vf-color-surface-raised);
--color-base-300: var(--vf-color-surface-sunken);
--color-base-content: var(--vf-color-text-default);
--color-primary: var(--vf-color-action-primary);
--color-primary-content: var(--vf-color-action-on-primary);
--color-secondary: var(--vf-color-action-secondary);
--color-neutral: var(--vf-color-surface-inverse);
--color-neutral-content: var(--vf-color-text-inverse);
--color-info: var(--vf-color-feedback-info);
--color-success: var(--vf-color-feedback-success);
--color-warning: var(--vf-color-feedback-warning);
--color-error: var(--vf-color-feedback-danger);
--radius-box: var(--vf-radius-lg);
--radius-field: var(--vf-radius-md);
--radius-selector: var(--vf-radius-sm);
--border: 1px;
--depth: 1;
--noise: 0;
}
[data-vf-scheme="dark"] { color-scheme: dark; }
Then card bg-base-200 and btn btn-primary take each scheme's colours. daisyUI 5 puts its
components in Tailwind's utilities layer, above variflow.
Bootstrap 5.3
- Turn on Tokens' framework map, which sets Bootstrap's own variables (
--bs-body-bg,--bs-primary,.btn-primary's and the rest) from your tokens in every scheme:$config['variflow_maps'] = ['bootstrap-5.3'];, then build (Variflow Tokens' guide, Retrofitting a site). - Build Bootstrap from Sass, in layers, with only the parts you use. No
.container, and the grid only for rows inside components. - Keep
data-bs-themein step with the scheme, so Bootstrap's dark-mode rules and the map agree.
scss/site.scss
@layer bs-base, variflow, bs-components, components, bs-utilities;
$enable-important-utilities: false; // see Gotchas
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";
@layer bs-base {
@import "bootstrap/scss/root";
@import "bootstrap/scss/reboot";
@import "bootstrap/scss/type";
}
@layer bs-components {
@import "bootstrap/scss/grid"; // rows inside components only
@import "bootstrap/scss/buttons";
@import "bootstrap/scss/card";
}
@layer bs-utilities {
@import "bootstrap/scss/helpers";
@import "bootstrap/scss/utilities/api";
}
// Bootstrap's button variables from the component.button tokens, set on the button itself so
// data-vf-variant on any ancestor picks the style.
@layer components {
.btn-vf {
--bs-btn-bg: var(--vf-component-button-background);
--bs-btn-color: var(--vf-component-button-text);
--bs-btn-border-color: var(--vf-component-button-border);
--bs-btn-hover-bg: var(--vf-component-button-background-hover);
--bs-btn-hover-color: var(--vf-component-button-text);
--bs-btn-hover-border-color: var(--vf-component-button-border);
--bs-btn-active-bg: var(--vf-component-button-background-pressed);
}
}
npm i bootstrap@5.3 sass
npx sass --load-path=node_modules --no-source-map --quiet-deps --silence-deprecation=import --style=compressed scss/site.scss build/site.css
Bootstrap 5.3's Sass uses @import, which Dart Sass reports as deprecated; the two flags quiet
that.
band.section.html and cards.component.html
<section {vfb:attrs}{if vfb:look == "dark"} data-bs-theme="dark"{if:elseif vfb:look} data-bs-theme="light"{/if} style="padding-top: {vfb:appearance:space_above}; padding-bottom: {vfb:appearance:space_below};">
<div data-vf-container="{vfb:container}">{vfb:content}</div>
</section>
<div {vfb:attrs}>
<div class="row g-3 row-cols-1{if vfb:narrow == 'stack'}{if:else} row-cols-md-3{/if}">
<div class="col"><div class="card h-100"><div class="card-body" data-vfb-field="one">{vfb:field:one:br}</div></div></div>
{if vfb:field:two}<div class="col"><div class="card h-100"><div class="card-body" data-vfb-field="two">{vfb:field:two:br}</div></div></div>{/if}
</div>
{if vfb:field:link}<p class="mt-3 mb-0"><a class="btn btn-vf" href="{vfb:field:link:url}" data-vfb-field="link">{vfb:field:link:label}</a></p>{/if}
</div>
row-cols-md-3 follows the screen, so the partial drops it when the column is narrow
("narrowLayout": {"below": 8, "name": "stack", "label": "Stacked"}).
Bulma 1.x
Bulma 1's colours are CSS variables, but most are built from hue, saturation and lightness
variables (--bulma-primary-h, -s, -l), which a token holding a colour can't fill. Map the
variables that take a whole colour, and style buttons from component tokens yourself. Use the
build without dark mode: Bulma's default build follows the visitor's system setting, which
Variflow's schemes don't.
css/site.css
@layer bulma, variflow, components;
@import "../node_modules/bulma/css/versions/bulma-no-dark-mode.css" layer(bulma);
@layer components {
:root, [data-vf-scheme] {
--bulma-scheme-main: var(--vf-color-surface-default);
--bulma-background: var(--vf-color-surface-raised);
--bulma-text: var(--vf-color-text-default);
--bulma-text-strong: var(--vf-color-text-default);
--bulma-border: var(--vf-color-border-default);
--bulma-link-text: var(--vf-color-text-link);
--bulma-body-background-color: var(--vf-color-surface-default);
--bulma-body-color: var(--vf-color-text-default);
--bulma-family-primary: var(--vf-font-family-body);
--bulma-radius: var(--vf-radius-md);
}
.button.is-vf {
background-color: var(--vf-component-button-background);
border-color: var(--vf-component-button-border);
color: var(--vf-component-button-text);
}
}
.card, .box and the text then take each scheme's colours. Don't use .columns and .column
for page layout; inside a component they're fine. The bundled file is large (about 550 KB
minified); building Bulma from its Sass with only the parts you use is smaller.
Foundation 6
Foundation's colours are Sass variables, and Foundation works out shades from them at build time,
so they need real values, not var(). Generate a Sass file from the live build's values, and
style anything that must follow schemes with the CSS variables.
-
Sass variables from a build step. The build's manifest (
themes/user/variflow-tokens/<site>/tokens.<hash>.json) lists every token with its value. This writes one Sass variable per token ($vf-color-action-primary: #2f5038;):// node tokens-to-scss.mjs path/to/tokens.<hash>.json > scss/_variflow.scss import { readFileSync } from 'node:fs'; const manifest = JSON.parse(readFileSync(process.argv[2], 'utf8')); for (const t of manifest.tokens) { const v = t.values?.root; if (typeof v === 'string') console.log('$' + t.cssName.slice(2) + ': ' + v + ';'); }Run it after each token build. These are the root values: schemes don't change them.
-
The XY grid inside components only.
scss/site.scss
@layer fd-base, variflow, fd-components, components;
@import "variflow";
$foundation-palette: (
primary: $vf-color-action-primary,
secondary: $vf-color-action-secondary,
success: $vf-color-feedback-success,
warning: $vf-color-feedback-warning,
alert: $vf-color-feedback-danger,
);
$global-radius: $vf-radius-md;
$body-font-family: $vf-font-family-body;
@import "foundation-sites/scss/foundation";
@layer fd-base {
@include foundation-global-styles;
@include foundation-typography;
}
@layer fd-components {
@include foundation-xy-grid-classes;
@include foundation-button;
@include foundation-card;
}
@layer components { // what must follow schemes and variants
.card { background: var(--vf-color-surface-raised); color: var(--vf-color-text-default); }
.button.vf { background-color: var(--vf-component-button-background); color: var(--vf-component-button-text); }
}
npm i foundation-sites@6 sass
npx sass --load-path=node_modules --no-source-map --quiet-deps --silence-deprecation=import --style=compressed scss/site.scss build/site.css
Open Props
Open Props is a set of variables (--size-3, --shadow-2, --ease-3) and an optional
normalize. Use it for what your tokens don't cover, such as easings, shadows and animations, and
keep colours, spacing and type on tokens. Point normalize's role variables at tokens.
css/site.css
@layer openprops, normalize, variflow, components;
@import "../node_modules/open-props/open-props.min.css" layer(openprops);
@import "../node_modules/open-props/normalize.min.css" layer(normalize);
@layer components {
:root, [data-vf-scheme] {
--surface-1: var(--vf-color-surface-default);
--surface-2: var(--vf-color-surface-raised);
--surface-3: var(--vf-color-surface-sunken);
--text-1: var(--vf-color-text-default);
--text-2: var(--vf-color-text-muted);
--link: var(--vf-color-text-link);
--brand: var(--vf-color-action-primary);
}
.card {
background: var(--vf-component-card-background);
border-radius: var(--vf-radius-lg);
box-shadow: var(--shadow-2);
transition: box-shadow 0.2s var(--ease-3);
}
}
Don't alias tokens to Open Props' palette (--vf-…: var(--blue-7)): that's the reverse of
rule 2. Put the colour in the token
file instead.
Gotchas
Classes that are only in a schema
Tailwind, UnoCSS and other tools that purge keep only the classes they find in the files they scan. Two kinds go missing:
- Class names in a schema's option values (
"value": "text-center") are in the.json, not the partial. Scan.jsonfiles in_sections/as well as.html. - Class names a partial builds (
grid-cols-{vfb:field:columns}) are in no file. Safelist them: Tailwind v4's@source inline("grid-cols-{2,3}"), Tailwind v3's and UnoCSS'ssafelist.
Prefer whole class names as option values, so scanning finds them. Scanning schemas also finds
words such as container and inline and generates those utilities; they're unused unless a
class names them.
Conditionals on text fields
Test a field with its bare variable:
{if vfb:field:eyebrow}<p class="eyebrow">{vfb:field:eyebrow}</p>{/if}
{if vfb:narrow == 'list'}…{/if}
Not with the value in quotes, {if "{vfb:field:eyebrow}" != ""}. That copies the text into the
conditional before EE reads it, so text with an apostrophe or a quote mark in it can end the string
early and break the conditional. The same goes for your own templates' channel fields: {if summary}, not {if "{summary}" != ""}. (Tokens fields are the exception: test their output, as
Variflow Tokens' guide says under About {if field}.)
!important beats schemes
An !important declaration beats every normal one, whatever its layer, and between layers it runs
backwards: an important rule in a lower layer beats one in a higher layer. So a framework's
important colour utility (Bootstrap's .bg-light, .text-dark, Tailwind's !bg-white) beats the
scheme's colours wherever it's used, and you can't override it from your components layer.
- Bootstrap:
$enable-important-utilities: false;before importing it, as above. In a layer the utilities still win by order. - Tailwind: don't use the
!modifier, or v3'simportant: true, for colours. - Don't put fixed colour utilities on an element that carries
{vfb:attrs}or sits in a scheme: map the utility to a token instead.
Framework grids follow the screen
A framework's md: breakpoint is the screen's width, not the column's. In the narrow column of an
8/4 a three-across row stays three across on a desktop screen. Use {vfb:narrow}, {vfb:span} or
a container query on the component (rule 1).