Wiki source code of Style variables

Last modified by Lucas Charpentier (Sereza7) on 2025/05/16

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
8.2	42	{{error}}
	43	CSS properties cannot currently be used in media queries. See [[this W3C draft about supporting CSS properties in media queries>>https://drafts.csswg.org/css-env-1/]] to get up-to-date information on this topic.
	44	{{/error}}
	45
5.4	46	==== Use them in a LESS stylesheet ====
5.2	47
5.3	48	{{info}}
5.2	49	It's recommended to use CSS variables in CSS stylesheets. LESS stylesheets are less versatile and more computationally costly.
5.3	50	{{/info}}
5.2	51
	52	{{code language="css"}}
	53	.box.box-custom {
	54	color: ~"var(--brand-color)";
	55	}
	56	{{/code}}
	57
6.1	58	==== Developing with CSS properties ====
	59
	60	Using the macro defined in the page shared on [[this gist>>https://gist.github.com/Sereza7/e4a78edc8c1c5865a44e84fc6a1b110d]], you can easily view all the CSS variables available in your context:
	61
	62	[[image:1744042284470-553.png\|\|height="495px" width="960px"]]
	63
	64	{{info}}
	65	Note that this is purely a development aide and the quality is not on par with XWiki Standard's quality.
	66	{{/info}}
	67
7.1	68	==== New CSS properties ====
6.1	69
7.1	70	Those properties were introduced in {{version since="17.3.0"}} {{/version}}and after. They are only available as CSS properties and do not have an equivalent in LESS variables.
	71
	72	\|Since\|Name\|Type (from CSS)\|Default value\|Meaning
	73	\|{{version since="17.3.0"}} {{/version}}\|100vw\|Size (vw)\|100vw\|Part of a workaround to get a unitless screen width.{{warning}}Avoid using it in customizations, CSS will likely improve and this workaround might get removed from XWiki at some point.{{/warning}}
	74	\|{{version since="17.3.0"}} {{/version}}\|int-viewport-width\|Size (unitless)\| \|Unitless screen width, useful for ratio calculations. {{warning}}Avoid using it in customizations, CSS will likely improve and this workaround might get removed from XWiki at some point.{{/warning}}
	75	\|{{version since="17.3.0"}} {{/version}}\|font-weight-regular\|Number\|400\|Font weight used for regular text in the interface.
	76	\|{{version since="17.3.0"}} {{/version}}\|font-weight-semibold\|Number\|700\|Font weight used for semibold text in the interface.
	77	\|{{version since="17.3.0"}} {{/version}}\|font-weight-bold\|Number\|900\|Font weight used for bold text in the interface.
	78
5.4	79	=== LESS variables ===
5.2	80
5.4	81	==== Where are LESS variables declared? ====
5.2	82
5.10	83	XWiki Standard has its LESS variables declared in a few files, mostly:
5.4	84
5.10	85	* ##variables.less## from the bootstrap module: pretty much everything to make the Bootstrap 3 design system work.
	86	* ##variables.less## from the flamingo module: XWiki's special variables and overrides for default values
	87	* ##variablesInit.vm## from the flamingo module:
	88	* [[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.
	89
5.4	90	{{info}}
	91	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 :)
	92	{{/info}}
	93
	94	==== Use them in a CSS stylesheet ====
	95
5.2	96	{{error}}
	97	It's not possible to use LESS variables in CSS stylesheets. Those variables need LESS compilation to work.
	98	{{/error}}
	99
5.4	100	==== Use them in a LESS stylesheet ====
5.2	101
	102	{{code language="lesscss"}}
	103	.box.box-custom {
	104	color: @brand-color;
	105	}
	106	{{/code}}
	107
5.4	108	=== Old colorTheme variables ===
5.2	109
	110	{{error}}
	111	Those variables are deprecated, avoid using them in any new development.
	112	{{/error}}
	113
5.4	114	==== Use them in a CSS stylesheet ====
5.2	115
5.3	116	{{warning}}
	117	You should consider using CSS variables instead.
	118	{{/warning}}
	119
5.5	120	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	121
	122	{{code language="css"}}#template('colorThemeInit.vm')
	123
	124	.box.box-custom {
	125	color: $theme.textPrimaryColor;
	126	}{{/code}}
	127
5.11	128	[[Learn more about the old color theme variables>>doc:extensions:Extension.Color Theme Application\|\|anchor="HUsingColorThemesvariables"]]
5.8	129
5.11	130
5.4	131	==== Really don't use them in a LESS stylesheet! ====
5.3	132
	133	{{error}}
	134	You should consider using LESS variables instead, or even migrating your stylesheet directly to native CSS with CSS variables.
	135	{{/error}}
	136
5.6	137	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	138
	139	{{code language="css"}}
	140	#template('colorThemeInit.vm')
	141
	142	.box.box-custom {
	143	color: $theme.textPrimaryColor;
	144	}
	145	{{/code}}
	146
5.1	147	== Migrating from LESS to CSS properties ==
	148
	149	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 :)
	150
	151	{{warning}}
5.11	152	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	153	{{/warning}}
	154
	155
	156	=== Syntax sugar ===
	157
	158	Native CSS is a bit more wordy than LESS:
	159
	160	* Variables start with a double dash (~-~-) instead of an arobase (@)
	161	* All use of a CSS variable should be made in a ##var## block.
	162	* All operations that you could write in your LESS must be made in a ##calc## block.
	163
5.12	164	{{warning}}
	165	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.
	166	{{/warning}}
5.1	167
	168	{{code language="css"}}
5.12	169	:root {
	170	--popover-arrow-color: var(--popover-bg);
	171	--popover-arrow-outer-width: calc(var(--popover-arrow-width) + 1px);
	172	}
5.1	173	{{/code}}
	174
	175	=== Units in CSS calculus ===
	176
	177	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:
	178
	179	* Addition and substraction, both values must have the same unit
	180	* Multiplications and divisions, only one value has an unit, the second one is unitless.
	181
	182	[[The exact rules>>https://developer.mozilla.org/en-US/docs/Web/CSS/calc#description]] are more precise than that.
	183
	184	=== Migrating color functions ===
	185
	186	To migrate LESS ##color functions##, you can use the CSS color or hsl functions:
	187
	188	{{code language="css"}}
5.12	189	:root {
	190	--popover-bg: hsl(from var(--well-bg) h s calc(l - 0.07));
	191	}
5.1	192	{{/code}}
	193
	194	HSL is useful for most operations, color is really only useful for transparency calculations.
	195	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.
	196
	197	{{info}}
	198	You can also use the CSS ##color-mix## with black or white to darken or lighten a color.
	199	{{/info}}
	200
	201	=== Using CSS variables in LESS ===
	202
	203	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.
	204
	205	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.
	206
5.12	207	{{code language="css"}}
	208	:root {
	209	-/**/-navbar-default-bg: ~"var(--brand-primary)";
	210	-/**/-navbar-default-border: ~"color-mix(in srgb, var(--navbar-default-bg), black 6.5%)";
	211	}
5.1	212	{{/code}}
	213
	214	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.
	215
5.8	216	== Migrating from old colortheme variables to CSS variables ==
	217
	218	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.
	219
	220	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