Verso and Elevate
Verso has no stylesheet of its own to fight. Every site carries its own copy of Elevate, and Verso asks it for exactly the CSS your classes need.
Elevate is a CSS compiler. You write classes like font:h3:bold or pd-x:d5 in your markup, and Elevate checks each one against your design tokens and writes only the CSS those classes need. Verso builds on that: templates, blocks and the rich text map are all styled with Elevate classes, and nothing else.
Where Elevate lives
Each site has its own copy of Elevate in the elevate/ folder. verso new copies the starter’s Elevate settings into elevate/, installs Elevate from npm and sets it up for you. If a site has no compiler yet, for example straight after a git clone, verso and verso build set it up the first time they run. Verso loads that copy through its API, elevate/core/api.ts, so it compiles with your tokens and rules, not a version of its own. Verso needs Elevate 1.2 or later.
| Folder | What it holds |
|---|---|
elevate/config/elevate.ts | Which folders and file types are scanned for classes, and extra CSS files to include |
elevate/config/design.ts | The design system: Elevate’s default tokens plus your own |
elevate/design/ | Your tokens: tokens.json, written by the Design panel, and site.ts, for extras written by hand |
elevate/extend/ | Plain CSS appended to the output, like @font-face rules in fonts.css |
Which classes get compiled
Elevate scans the folders listed in Watch, in files whose extension is in FileTypes, and picks up every class="…" and class='…'. A new Verso site watches ./templates, ./parts, ./blocks and ./public, in HTML and JavaScript files. The "rich" map in verso.json is compiled too, so classes you give rich text elements are checked like any other.
const options = {
Watch: ['./templates', './parts', './blocks', './public'],
FileTypes: ['html', 'js'],
Output: './dist',
Extend: ['./elevate/extend/fonts.css'],
ClassRegex: [
/\bclass\s*=\s*"([^"]*)"/g,
/\bclass\s*=\s*'([^']*)'/g,
],
SafeList: []
}
If your own scripts live somewhere else and add classes, add their folder here too. JavaScript on a Verso site explains how.
While you edit
The editor compiles once when it starts, and again whenever something in templates/, parts/, blocks/, public/, verso.json or elevate/ changes. The new stylesheet replaces the old one without losing your place. If a class is wrong, the page still opens and the problem is listed in the editor’s problem panel, with the file and line.
When a class is wrong
A build stops at the first class Elevate can’t compile. Verso finds the class list on that line, checks it, and names the class:
× templates/doc.html, line 14
The class "pd:d99" isn't valid. "pd" takes spacing tokens, and "d99" isn't one
Change or remove that class in the template.
A bad class in the rich text map is reported against verso.json and names the element it belongs to. Publish runs the same checks first, and refuses to publish while anything would break the live site.
Check before you ship
Run a build locally before you push. It runs every check the host will.
npm run build
npm run elevate -- check "row gap:d4 /md/ col"
npm run elevate -- describe
check tests a class list on its own and names each bad class. describe prints the whole design system as JSON: breakpoints, tokens, rules and properties. You don’t need to run npm run elevate to watch files on a Verso site, because the editor already compiles.
A few habits that help
- Breakpoint markers go at the end of a class list. Everything after
/md/applies from that breakpoint up:col gap:d4 /md/ row gap:d8. - States wrap their classes:
@hover:[text:proof-2], with underscores between several, like@hover:[bg-color:ink_text:paper]. containcentres a column and pads its sides: d5 on phones, d8 frommd, and 16rem from3xl(1920 pixels). If that is too generous for your layout, end the list with/3xl/ pd-x:d8.