Wiki source code of Style variables

Version 5.12 by Lucas Charpentier (Sereza7) on 2025/04/04

version	line-number	content
5.1	1	{{toc/}}
	2
	3	== What is a style variable? ==
	4
	5	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>>doc:dev:Community.CodeStyle.XhtmlCssCodeStyle.WebHome\|\|anchor="HCSS"]] makes the use of these variables mandatory in XWiki Standard development. It's recommended to rely on those for your own custom developments too :)
	6
	7	They provide some level of consistency in the UI:
	8
	9	* It will be harder for customizations to have unwanted effects
	10	* 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.
	11	* It's straightforward for your custom development components to be compatible with the color themes applied on multiple wikis
	12
	13	== How to use style variables? ==
	14
5.9	15	Currently, XWiki Standard with its Flamingo Skin supports three kinds of style variables. They are (ranging from the oldest to the newest):
5.1	16
	17	* The old colorTheme variables
	18	* The LESS variables (Flamingo colorTheme + design system inherited from bootstrap + Misc additions from the Flamingo skin)
	19	* {{version since="17.3.0RC1"}}The CSS properties{{/version}}
	20
	21	(% class="wikigeneratedid" %)
5.11	22	All of these variables are supposed to be used in .css files, .less files and their respective StyleSheet Extensions's contents.
5.1	23
5.4	24	=== Using CSS properties {{version since="17.3.0"}} {{/version}} ===
5.1	25
5.4	26	==== Where are CSS properties declared? ====
5.2	27
5.4	28	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.
	29
	30	{{info}}
	31	CSS properties can also be declared pretty much anywhere in your custom stylesheets using standard CSS syntax :)
	32	{{/info}}
	33
	34	==== Use them in a CSS stylesheet ====
	35
5.2	36	{{code language="css"}}
	37	.box.box-custom {
	38	color: var(--brand-color);
	39	}
	40	{{/code}}
	41
5.4	42	==== Use them in a LESS stylesheet ====
5.2	43
5.3	44	{{info}}
5.2	45	It's recommended to use CSS variables in CSS stylesheets. LESS stylesheets are less versatile and more computationally costly.
5.3	46	{{/info}}
5.2	47
	48	{{code language="css"}}
	49	.box.box-custom {
	50	color: ~"var(--brand-color)";
	51	}
	52	{{/code}}
	53
5.4	54	=== LESS variables ===
5.2	55
5.4	56	==== Where are LESS variables declared? ====
5.2	57
5.10	58	XWiki Standard has its LESS variables declared in a few files, mostly:
5.4	59
5.10	60	* ##variables.less## from the bootstrap module: pretty much everything to make the Bootstrap 3 design system work.
	61	* ##variables.less## from the flamingo module: XWiki's special variables and overrides for default values
	62	* ##variablesInit.vm## from the flamingo module:
	63	* [[The flamingo Color Themes>>doc:extensions:Extension.Flamingo Theme Application\|\|anchor="HHowtocreateanewtheme"]], those variables can be viewed and edited directly in the Administrator UI but they do not cover everything in the skin.
	64
5.4	65	{{info}}
	66	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 :)
	67	{{/info}}
	68
	69	==== Use them in a CSS stylesheet ====
	70
5.2	71	{{error}}
	72	It's not possible to use LESS variables in CSS stylesheets. Those variables need LESS compilation to work.
	73	{{/error}}
	74
5.4	75	==== Use them in a LESS stylesheet ====
5.2	76
	77	{{code language="lesscss"}}
	78	.box.box-custom {
	79	color: @brand-color;
	80	}
	81	{{/code}}
	82
5.4	83	=== Old colorTheme variables ===
5.2	84
	85	{{error}}
	86	Those variables are deprecated, avoid using them in any new development.
	87	{{/error}}
	88
5.4	89	==== Use them in a CSS stylesheet ====
5.2	90
5.3	91	{{warning}}
	92	You should consider using CSS variables instead.
	93	{{/warning}}
	94
5.5	95	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.
5.3	96
	97	{{code language="css"}}#template('colorThemeInit.vm')
	98
	99	.box.box-custom {
	100	color: $theme.textPrimaryColor;
	101	}{{/code}}
	102
5.11	103	[[Learn more about the old color theme variables>>doc:extensions:Extension.Color Theme Application\|\|anchor="HUsingColorThemesvariables"]]
5.8	104
5.11	105
5.4	106	==== Really don't use them in a LESS stylesheet! ====
5.3	107
	108	{{error}}
	109	You should consider using LESS variables instead, or even migrating your stylesheet directly to native CSS with CSS variables.
	110	{{/error}}
	111
5.6	112	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.
5.3	113
	114	{{code language="css"}}
	115	#template('colorThemeInit.vm')
	116
	117	.box.box-custom {
	118	color: $theme.textPrimaryColor;
	119	}
	120	{{/code}}
	121
5.1	122	== Migrating from LESS to CSS properties ==
	123
	124	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 :)
	125
	126	{{warning}}
5.11	127	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.
5.1	128	{{/warning}}
	129
	130
	131	=== Syntax sugar ===
	132
	133	Native CSS is a bit more wordy than LESS:
	134
	135	* Variables start with a double dash (~-~-) instead of an arobase (@)
	136	* All use of a CSS variable should be made in a ##var## block.
	137	* All operations that you could write in your LESS must be made in a ##calc## block.
	138
5.12	139	{{warning}}
	140	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.
	141	{{/warning}}
5.1	142
	143	{{code language="css"}}
5.12	144	:root {
	145	--popover-arrow-color: var(--popover-bg);
	146	--popover-arrow-outer-width: calc(var(--popover-arrow-width) + 1px);
	147	}
5.1	148	{{/code}}
	149
	150	=== Units in CSS calculus ===
	151
	152	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:
	153
	154	* Addition and substraction, both values must have the same unit
	155	* Multiplications and divisions, only one value has an unit, the second one is unitless.
	156
	157	[[The exact rules>>https://developer.mozilla.org/en-US/docs/Web/CSS/calc#description]] are more precise than that.
	158
	159	=== Migrating color functions ===
	160
	161	To migrate LESS ##color functions##, you can use the CSS color or hsl functions:
	162
	163	{{code language="css"}}
5.12	164	:root {
	165	--popover-bg: hsl(from var(--well-bg) h s calc(l - 0.07));
	166	}
5.1	167	{{/code}}
	168
	169	HSL is useful for most operations, color is really only useful for transparency calculations.
	170	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.
	171
	172	{{info}}
	173	You can also use the CSS ##color-mix## with black or white to darken or lighten a color.
	174	{{/info}}
	175
	176	=== Using CSS variables in LESS ===
	177
	178	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.
	179
	180	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.
	181
5.12	182	{{code language="css"}}
	183	:root {
	184	-/**/-navbar-default-bg: ~"var(--brand-primary)";
	185	-/**/-navbar-default-border: ~"color-mix(in srgb, var(--navbar-default-bg), black 6.5%)";
	186	}
5.1	187	{{/code}}
	188
	189	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.
	190
5.8	191	== Migrating from old colortheme variables to CSS variables ==
	192
	193	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 :) ). Those oldColorTheme -> Less variables mappings are available in the ##variablesInit.vm## template.
	194
	195	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.

Wiki source code of Style variables

Quick Links

Navigation

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected