Customizing Citizen styles

This page is about how you can customize Citizen styles on your wiki.

Click here for information on how to adapt Citizen styles on your wiki.

Quick start

1. If you don't know how to write CSS and use Dev Tools, it is highly recommended to learn those to make your time much easier! Guide on DevTools
2. Set $wgAllowSiteCSSOnRestrictedPages to true to allow site styles to work on some special pages (e.g. Special:UserLogin).
3. Try changing --color-primary__h to a different value in MediaWiki:Citizen.css on your wiki:

:root {
    /* Pink is the new black */
    --color-primary__h: 320;
}

Changing color scheme

Citizen uses CSS variables to control the color scheme of the UI.

It is recommended to use Citizen CSS variables directly because they are adapted to the current theme.

Supported extensions use the same variables. Please feel free to open an issue or submit a PR if you want to add new support.

Primary color

Citizen uses the HSL syntax for primary color to calculate right colors for different themes, including surface colors, text colors, etc.

Primary colors are then apply throughout all UI elements, including all supported extensions through skinStyles.

By default, Citizen uses the Wikimedia UI default primary color: #36c / hsl(220,60%,50%)

To change your primary color, simply convert your desired color to HSL to set the following variables:

Property	Description	Default value
--color-primary__h	Hue of primary color, this will affect other text and surface colors	220
--color-primary__s	Saturation of primary color in light mode	60%
--color-primary__l	Lightness of primary color in light mode	50%

Themes

You can use these class to define custom styles for each theme.

For more detailed usage on defining specific styles for each theme, see the guide for adapting dark mode on MediaWiki.

Class	Description
.skin-theme-clientpref-light	Light theme
.skin-theme-clientpref-night	Dark theme
.skin-theme-clientpref-os	Auto theme

Surface color

Property	Description
--color-surface-0	Site background only (e.g. surface that has the same color as site background)
--color-surface-1	Surface background 1 (e.g. modal, dropdown) (this has the same color as site background (#fff) in light mode)
--color-surface-2	Surface background 2
--color-surface-3	Surface background 3
--color-surface-4	Surface background 4

Text color

Property	Description
--color-base	Base text color (e.g. body text)
--color-emphasized	Emphasized text color (e.g. title)
--color-subtle	Subtle text color (e.g. caption)

Examples

To customize light theme color scheme, you can:

/* Make light theme great again */
:root.skin-theme-clientpref-light {
    --color-surface-0: red;
    --color-surface-1: lime;
    --color-surface-2: fuchsia;
    --color-surface-3: yellow;
    --color-surface-4: aqua;
    --color-base: blue;
    --color-base--emphasized: darkblue;
    --color-base--subtle: cornflowerblue;
}

Changing fonts

Citizen uses CSS variable to define fonts used through the skin and extension styles.

You can change the default fonts by simply redefining the CSS variables.

Since Citizen uses variable fonts heavily, it is recommended to use a variable font for replacement so the font styles are preserved.

Property	Description	Default value
--font-family-citizen-base	Default fonts, used in most places	'Roboto'
--font-family-citizen-serif	Serif fonts, used in blockquotes and some cases	'Roboto Serif'
--font-family-citizen-monospace	Monospace fonts, used in editors and code blocks	'Roboto Mono'

Examples

To change the base font to the best font aka Comic Sans MS, you can:

/* Bless the wiki with the pinnacle of typography */
:root {
    --font-family-base: 'Comic Sans MS';
}

Changing page width

Citizen uses CSS variable --width-layout to define page content width. You can redefine the variable on either the html or the body element.

Option	Selector	Default value
Standard	:root.citizen-feature-custom-width-clientpref-standard	1080px
Wide	:root.citizen-feature-custom-width-clientpref-wide	1600px
Full	:root.citizen-feature-custom-width-clientpref-full	100vw

Examples

To change the page width on the WasabiMayo page, you can:

/* Make WasabiMayo full-width */
.page-WasabiMayo {
    --width-layout: 100vw;
}