Contents

Using a CSS variable instead of a typed value

Point a setting at a named value your own site already defines — a brand colour, a spacing step — instead of typing the number or colour into RuleCMS.

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 the page it is sitting on 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, and everything else on the site refers to them by name. 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 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. What RuleCMS cannot check is whether the name means anything, because it almost never exists in RuleCMS at all: it exists in your application. That one fact is behind everything in "Watch out for" below, and it is worth reading before you use this.

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

OptionWhat you will see
ValueThe 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 variableYou 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 in your site's stylesheet and you do not want a second copy of the hex codes inside RuleCMS.
  • 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

  1. Open the setting in the Modify drawer and look for the "Value / CSS variable" toggle just above its input.
  2. Click "CSS variable". The number, colour picker, or dropdown is replaced by a single text box.
  3. 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)".
  4. Nothing will change on the composer canvas. Open the widget on a page in the application that defines the name to see the result.
  5. Click "Value" to go back to typing a value yourself.

Watch out for

  • A CSS variable does not preview in the composer. The canvas has no idea what your names mean, so the setting will look as though it did nothing at all. This is the single biggest surprise: check the widget on a real page in your application before deciding it is broken.
  • RuleCMS does not check that the name exists, and cannot — the value normally lives only in your application. A name your stylesheet never defines produces nothing, silently, with no warning and no fallback. A typo behaves exactly 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.

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