Style variables

Last modified by Lucas Charpentier (Sereza7) on 2025/04/23

What is a style variable?

A style variable represents a value shared across all of XWiki's style sheets. These values are meant to be used instead of hard-coding them in stylesheets. Our CSS codestyle makes the use of these variables mandatory in XWiki Standard development. It's recommended to rely on those for your own custom developments too emoticon_smile

They provide some level of consistency in the UI:

  • It will be harder for customizations to have unwanted effects
  • XWiki can provide colors that work well together by default. Among other things, it can help make sure all your components respect some minimum contrast.
  • It's straightforward for your custom development components to be compatible with the color themes applied on multiple wikis

How to use style variables?

Currently, XWiki Standard with its Flamingo Skin supports three kinds of style variables. They are (ranging from the oldest to the newest):

  • The old colorTheme variables
  • The LESS variables (Flamingo colorTheme + design system inherited from bootstrap + Misc additions from the Flamingo skin)
  • XWiki 17.3.0+ The CSS properties

All of these variables are supposed to be used in .css files, .less files and their respective StyleSheet Extensions's contents.

Using CSS properties XWiki 17.3.0+  

Where are CSS properties declared?

XWiki standard CSS properties are declared in the file cssVariablesInit.css . Those variables from are still unstable and not documented here. Starting in XWiki 18, those variables should become stable and be documented with detail here.

Information

CSS properties can also be declared pretty much anywhere in your custom stylesheets using standard CSS syntax emoticon_smile

Use them in a CSS stylesheet

.box.box-custom {
 color: var(--brand-color);
}

Use them in a LESS stylesheet

Information

It's recommended to use CSS variables in CSS stylesheets. LESS stylesheets are less versatile and more computationally costly.

.box.box-custom {
 color: ~"var(--brand-color)";
}

Developing with CSS properties

Using the macro defined in the page shared on this gist, you can easily view all the CSS variables available in your context:

1744042284470-553.png

Information

Note that this is purely a development aide and the quality is not on par with XWiki Standard's quality.

New CSS properties

Those properties were introduced in XWiki 17.3.0+  and after. They are only available as CSS properties and do not have an equivalent in LESS variables.

SinceNameType (from CSS)Default valueMeaning
XWiki 17.3.0+  100vwSize (vw)100vwPart of a workaround to get a unitless screen width.WarningAvoid using it in customizations, CSS will likely improve and this workaround might get removed from XWiki at some point.
XWiki 17.3.0+  int-viewport-widthSize (unitless) Unitless screen width, useful for ratio calculations. WarningAvoid using it in customizations, CSS will likely improve and this workaround might get removed from XWiki at some point.
XWiki 17.3.0+  font-weight-regularNumber400Font weight used for regular text in the interface.
XWiki 17.3.0+  font-weight-semiboldNumber700Font weight used for semibold text in the interface.
XWiki 17.3.0+  font-weight-boldNumber900Font weight used for bold text in the interface.

LESS variables

Where are LESS variables declared?

XWiki Standard has its LESS variables declared in a few files, mostly:

  • variables.less from the bootstrap module: pretty much everything to make the Bootstrap 3 design system work.
  • variables.less from the flamingo module: XWiki's special variables and overrides for default values
  • variablesInit.vm from the flamingo module:
  • The flamingo Color Themes, those variables can be viewed and edited directly in the Administrator UI but they do not cover everything in the skin.
Information

LESS variables can also be declared in any of your custom LESS stylesheets. If you can't find it in the xwiki-platform codebase, it's probably from a customization emoticon_smile

Use them in a CSS stylesheet

Error

It's not possible to use LESS variables in CSS stylesheets. Those variables need LESS compilation to work.

Use them in a LESS stylesheet

.box.box-custom {
  color: @brand-color;
}

Old colorTheme variables

Error

Those variables are deprecated, avoid using them in any new development.

Use them in a CSS stylesheet

Warning

You should consider using CSS variables instead.

Make sure the content of your stylesheet is parsed. This will allow the use of Velocity Templating Language (VTL) in your stylesheet. The old colorTheme do rely on VTL to work properly. You also need to make sure you import the declaration of the variables done in the colorThemeInit.vm template so that your stylesheet compiles to a consistent result in any context.

 #template('colorThemeInit.vm')

.box.box-custom {
 color: $theme.textPrimaryColor;
}

Learn more about the old color theme variables

Really don't use them in a LESS stylesheet!

Error

You should consider using LESS variables instead, or even migrating your stylesheet directly to native CSS with CSS variables.

Make sure the content of your stylesheet is parsed. This will allow the use of Velocity Templating Language (VTL) in your stylesheet. The old colorTheme do rely on VTL to work properly. You also need to make sure you import the declaration of the variables done in the colorThemeInit.vm template so that your stylesheet compiles to a consistent result in any context.

#template('colorThemeInit.vm')

.box.box-custom {
 color: $theme.textPrimaryColor;
}

Migrating from LESS to CSS properties

This section contains a few points that could be important when migrating LESS styles to using the CSS properties. Those are not community rules to be followed, but just indications to make it easier to migrate emoticon_smile

Warning

Today, there is no way to migrate any LESS mixin to CSS easily. In order to migrate any advanced use of mixins, an additional class should be added for the styles on the HTML.

Syntax sugar

Native CSS is a bit more wordy than LESS:

  • Variables start with a double dash (--) instead of an arobase (@)
  • All use of a CSS variable should be made in a var block.
  • All operations that you could write in your LESS must be made in a calc block.
Warning

Contrary to LESS variables that are global by default, CSS properties must be defined in a block. Either their own with the @property query, or inside a ruleset. Typically, in order to make CSS properties global like LESS ones, just put their assignations in a :root { } block.

:root {
 --popover-arrow-color:                 var(--popover-bg);
 --popover-arrow-outer-width:           calc(var(--popover-arrow-width) + 1px);
}

Units in CSS calculus

LESS doesn't have any clearly defined unit system. CSS has a very strict unit system (some improvements to make it a bit looser and easier to use are discussed though). If a formula doesn't work in CSS, it's probably because the units do not respect the constraint of the operators:

  • Addition and substraction, both values must have the same unit
  • Multiplications and divisions, only one value has an unit, the second one is unitless.

The exact rules are more precise than that.

Migrating color functions

To migrate LESS color functions, you can use the CSS color or hsl functions:

:root {
 --popover-bg: hsl(from var(--well-bg) h s calc(l - 0.07));
}

HSL is useful for most operations, color is really only useful for transparency calculations.
LESS color functions work directly with additions: darken(@well-bg, 7%) is the same as the snippet above. This is slightly different from calc( l * (1-0.07)) which was how I assumed LESS handled its operations at first.

Information

You can also use the CSS color-mix with black or white to darken or lighten a color.

Using CSS variables in LESS

Sometimes you want to start migrating a file without being able to move it all at once. In this kind of situation, you'll need to know about how to use CSS variables in a LESS file.

The LESS parser we use in XWiki standard is not maintained enough to ensure a good compatibility with current CSS. It does not work well with CSS variables directly. The usual solution to escape things in LESS works well for most cases: a tilde and the escaped content in between quotes.

:root {
 -/**/-navbar-default-bg:                ~"var(--brand-primary)";
 -/**/-navbar-default-border:            ~"color-mix(in srgb, var(--navbar-default-bg), black 6.5%)";
}

But, a quirk of the parser is that this syntax does not work when we're trying to use it for an assignation. One hack that's not too bad looking that works for those variable assignations is to add an empty comment block in the middle. It prevents the LESS parser from associating the two dashes together and assume this is the end of an HTML comment. You can see this workaround in the example above.

Migrating from old colortheme variables to CSS variables

There is no "easy" way to do this kind of migration because the old colorTheme variables do not map 1 to 1 to CSS variables. You might want to check how they got mapped to LESS variables to get an idea of CSS properties that have similar values (or just use the CSS properties with the semantics corresponding to your situation emoticon_smile ). Those oldColorTheme -> Less variables mappings are available in the variablesInit.vm template.

Once you removed all the old colortheme variables from your stylesheet, you can also remove the call to the colorThemeInit.vm template and don't need to parse it anymore.

Get Connected