Using a CSS variable instead of a typed value

Point a setting at a named token — a brand colour, a spacing step — instead of typing the number or colour into RuleCMS. The value can come from your site, from this widget’s catalog, or both.

In plain English

Almost every setting that takes a size, a colour, or a style choice has a small "Value / CSS variable" toggle above it. Left on "Value" you work as you always have: type 16px, pick #1a4f8a, choose "solid". Switch it to "CSS variable" and the input is replaced by a single text box where you type a name instead — something like --brand-space-medium. From then on the widget does not carry a value of its own for that setting; it asks what that name means.

This is for teams with a design system. Your application almost certainly already keeps its palette, its spacing steps, its type scale, and its shadows as named values in its own stylesheet. Copying those numbers into a widget gives you the right look today and a second copy to maintain forever. Pointing at the name instead means the widget simply follows: rebrand the palette, or let a visitor switch to dark mode, and the widget changes with everything else because it never had an opinion of its own.

The name can get its value in two places. Your site can define it, the way design systems always have. Or you can add it to this widget’s CSS Variables catalog in RuleCMS, in which case the composer and Preview show that value, and publish sends it with the embed. The project CSS Variables page is only the template copied onto a new widget. The full picture is on the CSS Variables guides. The name must start with two hyphens and can then contain letters, numbers, hyphens, and underscores — that is the shape the web requires, and RuleCMS checks it while you type.

For Border and Box Shadow you get a choice of how much to hand over. Design systems usually ship those as one complete value — --border-hairline holding "1px solid #ddd", or --shadow-md holding "0 2px 8px rgba(0,0,0,.15)" — so the toggle at the top of the setting lets you name the whole thing at once. If you would rather keep control of most of it, each part has its own toggle too, so you can take the shadow colour from a variable while typing the offsets and blur yourself.

What each option does

Option	What you will see
`Value`	The normal mode, and the one every setting starts in. You type the number, pick the colour, or choose from the list, and RuleCMS stores exactly that.
`CSS variable`	You type the name of a value your application defines. RuleCMS stores only the name and asks the browser to look it up when the page loads.

When you would use it

Your brand colours already live as named tokens — in your site's stylesheet, in this widget’s catalog, or both — and you do not want a second copy of the hex codes inside the widget JSON.
Your spacing scale is fixed — every gap on the site is one of a handful of steps — and a widget should use those steps rather than numbers someone typed by eye.
Your application offers light and dark themes by swapping what the names mean. A widget built on names follows the theme with no extra work.
Your design system publishes a whole border or a whole shadow as one named value, and you want the widget to use it exactly as everything else on the site does.

How to change it

Open the setting in the Modify drawer and look for the "Value / CSS variable" toggle just above its input.
Click "CSS variable". The number, colour picker, or dropdown is replaced by a single text box.
Type the name exactly as your application defines it, starting with two hyphens — for example --brand-space-medium. The help text underneath confirms what will be published, such as "Renders as var(--brand-space-medium)".
If the name is in this widget’s CSS Variables catalog, the canvas and Preview update. If it only exists on your live site, open the widget on a page that defines the name to see the result.
Click "Value" to go back to typing a value yourself.

Watch out for

If the name is not in this widget’s catalog, it will not preview in the composer. The canvas only knows names this widget defines. A token that exists solely in your application still works on the published page — check it there before deciding the setting is broken.
RuleCMS does not invent a fallback if the name is missing from both the catalog and the host page. A typo or an undefined name produces nothing, silently. It behaves like a typo in a CSS class name.
The name has to start with two hyphens. If you type "brand-space-medium" or "$space-md" the box turns red and nothing is saved, so the last name that was valid stays in place.
A setting is either a value or a variable, never both. There is no typed value held in reserve for browsers that cannot find the name.
Switching back to "Value" brings back the number or colour you had before on most settings, but not on Opacity or on the dropdown and diagram pickers. Those hold a single value with nowhere to keep your old choice alongside the name, so they come back empty and you will need to choose again.
Ask whoever owns your stylesheet which names are safe to use. A variable that is only defined inside one component of your application will not resolve for a widget placed somewhere else on the page — unless that name is also in this widget’s catalog.

Related settings

For developers

The technical reference for what this setting produces: MDN: Using CSS custom properties (variables). You do not need any of it to use the setting — it is there for whoever is building the components or debugging the published page.

Where to go next

Back to the full attribute reference
widget CSS Variables — this widget's catalog, which is what the canvas resolves. The project CSS Variables page is the template for the next widget you create.
The Composer — the editing surface these settings live in.
Publishing — how a change like this reaches your live site.